> ## Documentation Index
> Fetch the complete documentation index at: https://gateway.forceaisecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a single-shot ephemeral agent

> Spawn a ForceAI-managed agent instance on demand, run one task, and let it hard-kill itself - all over the runtime API.

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

<Note>
  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
</Note>

## The single-shot flow

<Steps>
  <Step title="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

    ```bash theme={null}
    curl -X POST https://YOUR_GATEWAY_DOMAIN/v1/runtime/agents \
      -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
      -d '{ "profile": "ephemeral-task", "agent_type": "chat", "task": "summarize this", "immediate_destroy": true }'
    # -> { "instance_id": "...", "state": "ready", "endpoint_url": "..." }
    ```
  </Step>

  <Step title="Run the task">
    Assign the single task to the instance. You get the result plus the updated instance

    ```bash theme={null}
    curl -X POST https://YOUR_GATEWAY_DOMAIN/v1/runtime/agents/$INSTANCE_ID/tasks \
      -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
      -d '{ "task": "summarize this document ...", "capability": "chat" }'
    # -> { "ok": true, "output_uri": "...", "instance": { "state": "completed" } }
    ```
  </Step>

  <Step title="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

    ```bash theme={null}
    curl -X DELETE "https://YOUR_GATEWAY_DOMAIN/v1/runtime/agents/$INSTANCE_ID?force=true" \
      -H "Authorization: Bearer $ADMIN_KEY"
    # -> { "state": "destroyed" }
    ```
  </Step>
</Steps>

## Profiles

The profile decides isolation, TTL, warm-pool, and destroy policy. Three ship by default:

| Profile          | Isolation   | On completion                          |
| ---------------- | ----------- | -------------------------------------- |
| `ephemeral-task` | per task    | hard-kill (single-shot)                |
| `session`        | per session | park IDLE, reusable until idle-timeout |
| `pooled`         | multiplexed | stays warm, reaped on TTL ceiling      |

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:

```bash theme={null}
FORCEAI_RUNTIME_SUBSTRATE=local_docker
FORCEAI_RUNTIME_RUNNER_IMAGE=forceai/runtime-runner:local
```

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

<Tip>
  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](/agents/isolated-sandbox)
</Tip>