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

# Agent runs

> Run an environment-declared agent harness as a durable, steerable execution with replayable events and private artifacts.

Agent Runs are the durable agent layer of the compute runtime. A run binds a
ready Workspace, ready Sandbox, one harness declared by the Workspace's pinned
Environment, and a durable agent Execution.

> [!NOTE]
>
> Agent Runs are provider-neutral. Requests select an Environment harness ID, not a compute provider or a shell command.

## Declare a harness

An Environment manifest must explicitly allow every agent harness:

```json theme={"dark"}
{
  "architecture": "amd64",
  "workingDirectory": "/workspace",
  "packages": [],
  "features": [],
  "environmentKeys": ["MODEL_TOKEN"],
  "agentHarnesses": [
    {
      "id": "review-agent",
      "argv": ["review-agent", "serve", "--jsonl"],
      "workingDirectory": "/workspace",
      "models": ["claude-fable-5-1"],
      "toolNames": ["git", "tests"],
      "environmentKeys": ["MODEL_TOKEN"]
    }
  ],
  "networkPolicy": { "mode": "open", "domains": [] },
  "secretReferences": []
}
```

Harnesses are bounded argv vectors. The manifest does not accept shell command
templates or environment-variable values. A run's model, tools, and environment
keys must be subsets of these harness declarations; environment keys must also
appear in the Environment-level `environmentKeys` list.

> [!WARNING]
>
> Generic `secretReferences` are rejected by the current Daytona and Sail providers. Secret-backed Agent Runs remain
> unavailable until tenant-scoped provider-vault bindings are implemented.

## Create a run

```bash theme={"dark"}
curl https://api.aireserve.com/v1/agent-runs \
  -H "Authorization: Bearer $AIRESERVE_API_KEY" \
  -H "Idempotency-Key: review-2026-11-06-001" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "11111111-1111-4111-8111-111111111111",
    "sandboxId": "22222222-2222-4222-8222-222222222222",
    "harness": "review-agent",
    "model": "claude-fable-5-1",
    "input": { "type": "text", "text": "Review the current change." },
    "configuration": {
      "maxTurns": 20,
      "timeoutSeconds": 900,
      "toolNames": ["git", "tests"],
      "environmentKeys": ["MODEL_TOKEN"]
    }
  }'
```

The `202` response contains the durable Run and Operation. Reusing the same
idempotency key with the same request replays that result; using it with a
different request returns `409`. The Operation resource uses the Run's public
ID and identifies its containing Sandbox through `resource.parent`.

Input bytes are written to private immutable Artifact storage. PostgreSQL and
Run events contain only the input digest and safe metadata.

The initial, steering, and cancellation harness envelopes carry the selected
model, bounded tool names, selected environment-key names, and safe endpoint
metadata when a Run uses an authenticated Endpoint. The runtime re-derives
these controls from durable state before delivery. Provider processes inherit
only the requested environment-key subset, never every secret present in the
Sandbox.

### CLI and MCP

Keep run input out of shell history. The CLI accepts the complete request from
a file or stdin and returns the exact API DTO with global `--json`:

```bash theme={"dark"}
aireserve agents runs create --file run.json
aireserve agents runs events "$RUN_ID" --after 17
aireserve agents runs steer "$RUN_ID" --file steer.json
aireserve agents runs artifacts list "$RUN_ID"
```

The event command reconnects with `Last-Event-ID` and exits nonzero when the
Run fails, is cancelled or times out. Over [MCP](https://docs.aireserve.com/connect/mcp.md), use
`create_agent_run`, `get_agent_run`, `get_agent_run_event_snapshot`,
`steer_agent_run`, `cancel_agent_run` and `list_agent_run_artifacts`.
Snapshot calls return `nextAfter`; pass it as the next `afterSequence`.

## Compute pricing

Sandbox Offers, Quotes, and Sandboxes disclose the compute provider. Requests
remain provider-neutral and cannot name or override a provider.

The pricing object also discloses `billingModel`:

* `reserved` settles the first reserved increment when the Sandbox becomes
  ready, then bills subsequent full increments and a final partial increment
  at the sealed Quote rate.
* `observed` releases the initial wallet hold when the Sandbox becomes ready,
  then bills completed minute-aligned windows from the provider's reported
  actual spend after its reporting lag. Provider nano-USD estimates are rounded
  conservatively up to exact six-decimal USD.

The initial hold is not a final charge for an `observed` offer. Usage windows
are durably reconciled so delayed provider reporting retries instead of
silently creating an unbilled interval.

## Follow and steer

Events are ordered by `sequence`. Reconnect an SSE client with the last
received sequence:

```bash theme={"dark"}
curl -N https://api.aireserve.com/v1/agent-runs/$RUN_ID/events \
  -H "Authorization: Bearer $AIRESERVE_API_KEY" \
  -H "Last-Event-ID: 17"
```

Steering uses that sequence as an optimistic cursor:

```bash theme={"dark"}
curl https://api.aireserve.com/v1/agent-runs/$RUN_ID/steer \
  -H "Authorization: Bearer $AIRESERVE_API_KEY" \
  -H "Idempotency-Key: review-steer-001" \
  -H "Content-Type: application/json" \
  -d '{
    "afterSequence": 17,
    "input": { "type": "text", "text": "Also run the focused tests." }
  }'
```

A stale `afterSequence` is rejected. Cancellation is also an idempotent
mutation at `POST /v1/agent-runs/{id}/cancel`.

## Artifacts and privacy

List metadata with `GET /v1/agent-runs/{id}/artifacts`. Fetch one Artifact to
mint a fresh short-lived download URL:

```bash theme={"dark"}
curl https://api.aireserve.com/v1/agent-runs/$RUN_ID/artifacts/$ARTIFACT_ID \
  -H "Authorization: Bearer $AIRESERVE_API_KEY"
```

Metadata listing requires compute `read`. Minting a download URL requires
compute `manage`; read-only API keys and organization members are refused.

Prompts, tool arguments, tool output, logs, checkpoints, and generated files
never appear in event payloads. Unrecognized stdout and all stderr are captured
as bounded private log Artifacts. Cross-organization identifiers return the
same `404` as unknown identifiers.

Agent input, steering, output, log, checkpoint, and file bytes are retained for
seven days by default, measured from each Artifact's `availableAt` time. The
Run, its events, and Artifact metadata remain durable after those bytes expire.
Expired or deleted Artifacts do not return a download URL.

Cleanup deletes the exact immutable object generation recorded for the
Artifact. If storage deletion fails, metadata remains available and cleanup
retries later; it is marked deleted only after storage confirms deletion.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.