Remote operations for the devices you already run.

WHO IT IS FOR

Teams that operate devices in the real world.

QUICKSTART

From zero to a live device in three steps.

1. 1

   Create a device

   Open the console, choose Add device, then enter a unique name, site and device type.

2. 2

   Copy the device token

   The token begins with fle_ and is shown once. Store it on that device as a secret.

3. 3

   Install the agent

   Run the generated command as root. The device appears online and begins polling for allowlisted operations.

curl -fsSL https://felania.com/install.sh -o /tmp/felania-install.sh
sudo sh /tmp/felania-install.sh

Safer enrollment: the installer prompts for the one-time device token without placing it in shell history or process arguments.

What it installs: a small shell agent, a separate update runner, curl and jq if missing, a root-only configuration file and a systemd or OpenWrt procd service. The agent makes outbound HTTPS requests only.

Guided onboarding: Console → Overview shows four workspace-derived milestones: create a device, receive its first heartbeat, complete a safe Runbook and deploy an application successfully. Felania updates the checklist from real activity; users never need to mark a step complete manually.

Per-device telemetry: Use the Device selector in Overview → Latest telemetry to pin a specific device. The selection is remembered for that workspace across live refreshes. Choose Auto · attention first to let Felania follow a warning device before a healthy one.

History and incidents: Select a device from the Overview list or choose Details in Device inventory. The detail view charts CPU, memory, disk and latency across one hour, 24 hours or seven days, then combines alerts, recoveries, direct commands, Runbooks and deployments into one device-specific timeline.

OPEN-SOURCE AGENT

Review the privileged code before you install it.

Felania Agent runs with root privileges because application deployment, service recovery and guarded agent replacement require operating-system access. The complete device agent and installer are published under the MIT License so operators can inspect that boundary before trusting it on a fleet.

License boundary: the MIT License covers only the files published in SmithJez/felania-agent. It does not grant rights to Felania trademarks or to the hosted service and private control-plane code.

ALERT INBOX

Work active incidents first. Keep history searchable.

Open Console → Operations to review fleet alerts. The inbox starts on Open, so resolved noise does not bury active work. Switch to All history or Resolved when investigating a recurring condition.

GUARDED UPDATES

Automatic when you want it. Recoverable when it fails.

Each device can use Manual or Automatic update mode from Console → Devices. Manual mode is the default. Choose Update now or queue update_agent from Remote Operations to start a manual update.

Why the runner is separate: agent updates never overwrite the small process responsible for recovery. A device always keeps current, previous and pending-update state until validation succeeds.

RUNBOOK CONSOLE

Repeatable remote response without an open terminal.

Open Console → Runbooks to run a reviewed sequence of allowlisted operations across one or more devices. Felania validates every parameter on the server, executes steps in order and keeps a per-device transcript with status, timing and bounded output.

Risk and approval model

Create a custom Runbook

1. 1

   Describe the response

   Owners choose Create Runbook and give the playbook a clear name and purpose.

2. 2

   Add validated steps

   Select one to eight operations. Fields such as service, target, log lines and heartbeat interval use the same validation as Remote Operations.

3. 3

   Run on a canary

   Select compatible Agent 1.7 devices and keep the default canary strategy for multi-device work.

4. 4

   Review the transcript

   Each run preserves its Runbook version and rendered steps, so later edits cannot change historical evidence.

Security boundary: Runbooks do not accept arbitrary shell, pipes, redirection or undeclared parameters. Service logs can contain application secrets, so grant console and API access only to trusted operators and rotate exposed credentials if sensitive output is captured.

Start a Runbook through the API

curl -X POST https://felania.com/api/v1/runbooks/rb_system_network_path/run \
  -H "Authorization: Bearer fla_YOUR_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceIds": ["dev_FIRST", "dev_SECOND"],
    "strategy": "canary",
    "parameters": { "TARGET": "felania.com" }
  }'

APPLICATION RELEASES

Canary first. Fleet only after health passes.

Felania Releases deploys Docker Compose workloads through the existing outbound agent. Open Console → Releases to enter the application-first workspace: Applications is the daily control surface, while Templates, New release, Credentials and History keep advanced tasks separated.

1. 1

   Choose the application

   Open the Applications tab and find the running workload. Its card shows the desired version, reported versions, drift and offline targets.

2. 2

   Deploy a new version

   Select Deploy new version. Felania copies the stored Compose file, registry, health target and current devices into a safe draft without returning secret values.

3. 3

   Change and preflight

   Enter a new unique version, update the image reference or Compose configuration, review target devices and run deployment preflight. Canary remains the default rollout strategy.

4. 4

   Follow the rollout

   After creation, the console opens History. The timeline shows ten releases at a time and keeps rollback, retry, output and audit context together.

services:
  app:
    image: ghcr.io/example/edge-display:2.4.0
    restart: unless-stopped
    environment:
      DATABASE_URL: ${DATABASE_URL}
    ports:
      - "8080:8080"

Browse a private Registry V2

1. 1

   Add and verify credentials

   In Console → Releases → Credentials, enter the HTTPS registry host, username and plaintext password or access token. For htpasswd, use the original password—not the bcrypt hash stored in the password file. Felania validates /v2/ before encrypting the credential.

2. 2

   Inspect a tag

   Choose Browse images, select a repository and then Inspect image. Felania reads its Registry V2 manifest, immutable digest, size and supported platforms such as linux/amd64 and linux/arm64.

3. 3

   Use the pinned image

   Choose Use pinned image to place an @sha256: reference into the Compose release. A later push that changes the original tag cannot silently change this release.

Deployment preflight

curl -X POST https://felania.com/api/v1/releases/preflight \
  -H "Authorization: Bearer YOUR_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  --data @release.json

Rotate or correct a login: choose Update login on the saved Registry card, enter the plaintext password again and select Verify & update login. The existing encrypted credential remains unchanged if verification fails.

Compatibility: the Registry must expose the Docker Distribution V2 catalog and tag endpoints. Some hosted registries or pull-only scoped credentials intentionally deny _catalog; those credentials can still deploy an explicitly entered image reference.

Application lifecycle controls

Device requirements: Felania Agent 1.8.2, Docker Engine and either Docker Compose v2 or docker-compose. Agent 1.8.2 stores command results locally, retries interrupted delivery and skips registry pulls for immutable images already present on the device. Secret values and registry tokens must be one line. Anyone with root access to a target device can inspect its runtime environment, so device operating-system security still matters.

DEVICE TEMPLATES

Reproduce a known-good application stack.

A Device Template is a deployment bundle built from the workloads currently reported by one source device. It stores the exact release ID for every application—not a moving “latest” version—so new machines receive the same known-good stack.

1. 1

   Prepare the source

   Confirm the source device is online and every installed workload version still exists as an active stored release in Felania.

2. 2

   Create from device

   Open Console → Releases → Templates → Create from device, name the template and select the known-good source. Review every application and exact version before saving.

3. 3

   Select new targets

   Choose Deploy template and select one or many compatible devices. A machine does not need to have received these applications before. The source device remains unselected unless you explicitly choose it.

4. 4

   Preflight and deploy

   Felania checks Agent 1.8.2, the guarded runner, Docker platform, image compatibility, conflicting rollouts and required encrypted variables for every release and target. Canary is the default strategy.

Share an existing secret safely: under Application secrets, choose Edit scope and move a device-scoped variable to its site or workspace. Felania preserves the encrypted value, never returns plaintext and records the scope change in the audit log.

{
  "strategy": "canary",
  "deviceIds": ["dev_target_01", "dev_target_02"]
}

Refresh semantics: editing a template captures a new numbered template version from the selected source and emits an audit event. Existing bundle runs keep their template name, version, release IDs and results.

Update available: Felania compares the immutable bundle with the latest workload report from its source device. A changed, added or removed application is highlighted with the stored and reported versions. Deployment keeps using the stored bundle until an Owner reviews and saves a new template version.

EDGE APP BLUEPRINTS

Deploy a supported app without writing Compose.

Open Console → Releases and choose a Blueprint. The guided form asks only for the image or version, ports and required encrypted variables. Felania renders a server-validated Compose file, shows a safe preview, then uses the same canary health gates and immutable protected snapshots as a manual release.

Trigger a Blueprint from GitHub Actions

1. 1

   Create an API key

   In Console → API, create a dedicated key and save it in the GitHub repository secret FELANIA_API_KEY.

2. 2

   Copy the generated workflow

   On a Ready Blueprint card, choose GitHub Action and save the result as .github/workflows/felania-deploy.yml.

3. 3

   Add Blueprint secrets

   If the Blueprint declares secret variables, create GitHub repository secrets with the same names. Non-secret values are workflow inputs.

4. 4

   Run the workflow

   Use Actions → Deploy with Felania → Run workflow. Supply an immutable version and a JSON array of target device IDs.

Safe automation: give each repository its own Felania API key, keep the workflow permission at contents: read, pin image versions and revoke the key when the integration is retired.

CORE CONCEPTS

Devices, sites and telemetry.

Every device belongs to one workspace and one site. A device identity is independent of its hardware, so it can represent a Linux computer, OpenWrt router, ESP32, gateway or another connected product.

Each heartbeat includes CPU, memory, disk, Wi-Fi signal when available, hostname, IP address, uptime, load average, kernel, agent version and operating-system metadata. Felania retains telemetry for 30 days by default.

Device lifecycle

Console workflow: open Console → Devices and choose Archive. Archived identities appear below the active inventory with Restore and, when safe, Purge controls.

Find a device quickly: search by device name, site, OS, hostname, agent version or platform. Sort the active inventory by attention status, name, site, last seen or version. The same search also filters archived identities.

Investigate one device: choose Details for historical charts and its incident timeline. Use Open operations to carry the same device into the allowlisted command console, or queue a guarded Agent update directly when the recovery runner is ready.

STATUS MODEL

A small state model you can trust.

TOKENS & SECURITY

Two credentials, two responsibilities.

Never place a Platform API key in browser JavaScript or firmware distributed to customers. Create separate keys for each integration and revoke them from the console when no longer needed.

BILLING & SUBSCRIPTION

Start small, then expand the fleet when you need it.

Every new workspace starts with a 14-day trial for up to 10 devices. A workspace Owner can open Console → Settings, choose a plan and complete the subscription through Stripe Checkout.

1. 1

   Choose a plan

   Only a workspace Owner can start Checkout. Select Starter, Pro or Business from the Workspace plan card.

2. 2

   Complete secure Checkout

   Stripe collects the billing details and payment method. Felania never receives or stores the complete card number. If Felania gave you a promotion code, choose Add promotion code in Checkout before paying.

3. 3

   Return to the console

   Stripe notifies Felania after a successful payment and the device limit updates automatically. No manual activation is required.

4. 4

   Change or cancel later

   Choose Manage billing in Settings. A scheduled cancellation keeps the subscription active through the paid billing period.

Checkout did not open? Confirm that you are signed in as the workspace Owner and reload Settings. Returning from Checkout without payment leaves the current plan unchanged.

FOUNDER FUNNEL

Measure the path to revenue without a paid analytics service.

The Console → Founder view is visible only to the Owner of Felania’s internal founder workspace. It combines privacy-light first-party website events with product and billing milestones already recorded by the platform. Customer workspace owners and team members cannot access platform-wide data.

Read the dashboard

1. 1

   Choose one window

   Use 7 days for launch feedback, 30 days for the normal operating view and 90 days when traffic is still sparse.

2. 2

   Follow the cohort

   Trials, activation, core value and paid status all begin with workspaces created inside the selected window, so later milestones describe the same acquisition cohort.

3. 3

   Fix the measured bottleneck

   The Founder Focus card selects the lowest valid adjacent conversion. Improve that hand-off before spending effort on additional traffic.

4. 4

   Compare sources by outcome

   Campaign sources are ranked by trials, activation and paid conversions—not page views alone. Links can use standard utm_source, utm_medium and utm_campaign parameters.

Privacy: funnel events do not store IP addresses, user-agent strings, fingerprints, email addresses or full referring URLs. The browser identifier rotates after 90 days, campaign attribution expires after 30 days, server events expire after 180 days, and Global Privacy Control or Do Not Track disables collection.

PLATFORM API

Connect Felania to your own product.

Create a Platform API key from Console → API. Send it as a Bearer token on every management request. The API is versioned under /api/v1 and returns JSON.

curl https://felania.com/api/v1/devices \
  -H "Authorization: Bearer fla_YOUR_PLATFORM_API_KEY"

const response = await fetch("https://felania.com/api/v1/summary", {
  headers: { Authorization: `Bearer ${process.env.FELANIA_API_KEY}` }
});

const fleet = await response.json();
console.log(`${fleet.online}/${fleet.total} devices online`);

Platform API keys are limited to 120 requests per minute per key. Device heartbeat limits are separate.

API REFERENCE

Available endpoints.