Agent runtimes

Each Perceive8 agent gets its own Fly.io app and Machine. This one-to-one mapping keeps agent data isolated and lets you manage compute and secrets per agent.

Lifecycle

1. Create an agent in the dashboard or via the API.
2. Publish the agent. The control plane provisions a Fly app, builds the runtime image, and starts a Machine.
3. Runtime state is tracked in public.agent_runtimes and surfaced in the dashboard.
4. Republish if the deployment fails or the Machine is destroyed.

Deployment status

An agent's deployment_status can be:

• pending — provisioning is in progress.
• published — the runtime is running and reachable.
• failed — provisioning failed; check the dashboard or POST /v1/agents/:id/republish to retry.

Provisioning and republishing

# Provision a runtime
POST /v1/agents/:id/runtime/provision

# Get runtime status
GET /v1/agents/:id/runtime

# Republish after a failure
POST /v1/agents/:id/republish

Secrets

Per-agent secrets are stored as Fly app-level secrets, never in the database. The public.agent_fly_secrets table only stores metadata (secret names). Set a secret with:

PUT /v1/agents/:id/secrets/:name

Use ${FLY_SECRET:NAME} as an environment variable value in the agent config to pull the secret from the Fly app env at runtime.

Provider keys

Tier-wide provider keys such as OPENROUTER_API_KEY, ANTHROPIC_API_KEY, and TAVILY_API_KEY are configured as control-plane environment variables and injected automatically into every openclaw agent Machine.

Webhooks

Each runtime is reachable on Fly's public edge at https://<fly-app>.fly.dev. The control plane proxies inbound webhooks via:

POST /v1/agents/:id/webhook

The proxy attaches the shared runtime secret so the agent can verify the request.

Engine and config

The RUNTIME_ENGINE is derived from agents.runtime_kind. An openclaw agent automatically gets RUNTIME_ENGINE=openclaw. Workspace-level defaults live in public.workspace_runtime_configs, and per-agent overrides live in public.agent_configs with config_type = 'env'. The config-sync process inside the runtime merges defaults and overrides and writes a .env file to OPENCLAW_STATE_DIR.