Skip to main content
The ForceAI Agent Runtime provisions agent instances on demand: it spawns an isolated instance with a scoped key, runs your task, and hard-kills it on completion. Unlike an A2A agent (a long-lived upstream you register), an ephemeral agent lives for one run. Everything is managed inside ForceAI
The runtime is admin-only. The default substrate is a no-op driver, so the API works out of the box; provisioning real containers is opt-in (see “Enable real containers”). Endpoints live on the backend control plane

​
The single-shot flow

1

Spawn an instance

Choose the ephemeral-task profile - per-task isolation, short TTL, and hard-kill on completion. The response is the instance with its state and a scoped endpoint
2

Run the task

Assign the single task to the instance. You get the result plus the updated instance
3

Kill it (single-shot)

With ephemeral-task the instance hard-kills itself on completion; the scoped key is revoked on teardown. You can also end it explicitly - which revokes the key immediately even if compute teardown lags

​
Profiles

The profile decides isolation, TTL, warm-pool, and destroy policy. Three ship by default: For a single-shot agent use ephemeral-task. For a chat that keeps its instance between turns use session

​
In the dashboard

Agents -> Agent Runtime lists live instances with their state and substrate. Spawn from a profile, run a task, and kill an instance from the table

​
Enable real containers

By default the runtime uses a no-op substrate, so spawn/run/kill work without Docker. To provision a real container per instance, set on the backend:
and give the backend access to a Docker daemon (mount /var/run/docker.sock) with the spawned containers on the same network as the gateway. The runner image must serve POST /run ({instance_id, step_id, capability, task} -> {"ok": true, "output_uri": "..."}) and GET /health. Mounting the Docker socket is root-equivalent, so keep it opt-in
When the agent runs untrusted or model-generated code, prefer the sandbox substrate over a plain container: it pins network egress to the gateway and keeps the scoped key out of the workload. See Run an agent in an isolated sandbox