Deployments & revisions

For the built-in runtimes, what you deploy is a small directory:

my-agent/
├─ agent.toml      # name, model, runtime family
├─ prompt.md       # the system prompt
├─ skills/         # optional — folders the agent loads when it needs them
└─ runtime/        # optional — a custom runtime image (coming soon)

agent.toml + prompt.md are all a built-in agent needs; skills/ and runtime/ are additive. A deployment is one attempt to turn source or uploaded behavior into a live agent. A successful attempt creates an immutable revision; failed, canceled, superseded, and skipped attempts remain deployment history but do not create one.

A Flue deployment packages a compiled Cloudflare app instead. It records revisions in the same API, but currently has one live Worker per agent rather than independently routable revision artifacts. Its staging and rollback behavior is therefore different.

Built-in runtime behavior can be deployed through the API/SDK, the oc CLI, or a repo push. A Flue app can be imported and built from GitHub in the dashboard, or deployed from a local checkout with oc agent deploy.

Revisions

A revision is an immutable, numbered record of one successful deployment. For a built-in runtime, it freezes the prompt, model, and skills used by new sessions. For Flue, it records the app deployment and Worker version that passed verification. An imported Flue agent begins undeployed, with no active revision; its first successful build and verification creates revision #1. Revisions are linear (the number only goes up) and never rewritten. Built-in runtime sessions keep the revision they started on; only new sessions pick up a change. Flue sessions share the agent’s live Worker, so a Worker deployment also changes the code used by existing sessions.

Field
`number`	Monotonic per agent (`1, 2, 3, …`).
`prompt` / `model`	The behavior at deployment time.
`skill_bundle_digest`	The skill files (a content-addressed bundle); `null` when there are no skills.
`digest`	A content hash of the behavior (used for change detection).

The agent itself holds only identity + bindings (name, runtime, credential, limits) plus a pointer to the active revision; prompt/model are served from that revision.

Deploy

POST /agents/:id/deployments is the common post-creation command. input.type: "inline" sends behavior directly (API / CLI / dashboard); input.type: "github" deploys an already-linked repo — see Deploy from a repo. Creating a new Flue agent from GitHub uses the atomic POST /agents/import command instead. An inline payload is the complete behavior — omitted fields aren’t inherited (prompt is required; omitted skills means no skills).

const deployment = await oc.agents.deployments.create("agt_123", {
  input: {
    type: "inline",
    prompt: "You triage pull requests.",
    model: "anthropic/claude-opus-4-8",
    skills: [{ path: "triage/SKILL.md", content: "---\nname: triage\ndescription: Triage a PR\n---\nSummarize the diff…" }],
  },
});

POST https://api.opencomputer.dev/v3/agents/agt_123/deployments
Authorization: Bearer $OPENCOMPUTER_API_KEY
Content-Type: application/json

{
  "input": {
    "type": "inline",
    "prompt": "You triage pull requests.",
    "model": "anthropic/claude-opus-4-8",
    "skills": [{ "path": "triage/SKILL.md", "content": "---\nname: triage\ndescription: Triage a PR\n---\nSummarize the diff…" }]
  }
}

# from a directory holding agent.toml + prompt.md + skills/
oc agent deploy

The response is a deployment:

{ "deployment": { "id": "dep_…", "state": "ready", "revision_id": "rev_…", "active": true } }

Inline deployments finish synchronously (state: "ready" with a revision_id) for the built-in runtimes. A Flue deploy returns state: "verifying" while the managed deploy runner uploads the agent Worker and waits for two consecutive healthy responses from that exact live Worker. Poll it like an asynchronous deployment (verifying to ready or failed). Repository deployments start at accepted; poll GET /agents/:id/deployments/:deployment_id and its durable log until terminal.

Staging vs activating

Isolated staging is not available for Flue. A Flue upload changes the one live Worker even when deployment metadata requests activate: false. Do not use --no-activate or a pinned revision as a Flue canary. See Flue deployment behavior.

By default a ready deployment is activated — its revision becomes what new sessions use. Pass activate: false to stage instead: the revision is created but not made active, so you can test it before it goes live.

// 1. stage a revision (not activated)
const { deployment } = await oc.agents.deployments.create("agt_123", { input: { type: "inline", prompt: "…" }, activate: false });

// 2. test it — a session pins the agent's ACTIVE revision by default; pass `revision`
//    to run the staged one instead
const session = await oc.sessions.create({ agent: "agt_123", revision: deployment.revision_id, input: "…" });

// 3. happy? promote it
await oc.agents.revisions.activate("agt_123", deployment.revision_id);

So revision on session create is how you exercise any non-active revision (a staged one, or an old one) without touching what’s live. For built-in repo deployments, the branch decides and activate is ignored: a push to the production branch activates, while another branch stages. Flue repository deployment accepts only its linked production branch because the current runtime has one live Worker and no isolated preview Worker.

Editing prompt/model via PATCH /agents/:id also deploys a revision — a shorthand for small edits.

Deploy from a repo

Import a Flue repository

Choose Agents → Create agent → Import from GitHub in the dashboard. OpenComputer inspects the selected branch and root without executing code, then creates the agent, source link, and first deployment as one retry-safe command. The OpenComputer agent’s editable display name is separate from agent.toml.name, which identifies the exported Flue entrypoint inside the built app. The managed path is deliberately narrow: one self-contained npm root, a committed package-lock.json, a compatible engines.node, and a local @flue/cli dependency. OpenComputer fetches the exact commit with a repository-scoped GitHub App token in a source sandbox, removes Git metadata and auth, then runs npm ci and the offline builder in a separate tokenless sandbox. npm lifecycle scripts do run in that ordinary disposable OpenComputer sandbox, but its request carries no source, platform, model, or deployment credential. The deployment detail page keeps one persisted chronological log and summarizes the attempt as Prepare, Build, and Deploy. An install/build failure leaves the imported agent visible and undeployed; it creates no revision and cannot start a session. Fix the source and push the production branch again.

Each later push that touches the linked root on the production branch automatically creates a Flue deployment. Non-production pushes do not create preview/staged Flue Workers. Deploy latest manually rebuilds the current production head when needed.

Link a built-in agent directory

Keep the agent directory (above) in Git and push to deploy. Install the OpenComputer GitHub App on the repo, then connect it to an agent:

await oc.agents.deploymentSource.link("agt_123", { repo: "acme/agents", path: "issue-fixer", productionRef: "main" });

POST https://api.opencomputer.dev/v3/agents/agt_123/deployment-source
Authorization: Bearer $OPENCOMPUTER_API_KEY
Content-Type: application/json

{ "repo": "acme/agents", "path": "issue-fixer", "production_ref": "main" }

oc agent link acme/agents --path issue-fixer --branch main

Linking deploys the current main HEAD right away (deploy_now: false / --no-deploy to skip). Then every push that touches the directory deploys:

push to main (production) → a new revision, activated.
push to another branch → a revision staged (test, then promote).
a push not touching the directory → no-op; identical directory content → skipped (no churn).

OpenComputer posts a commit status (queued → ready / failed) so a deployment’s result shows in GitHub. For built-in behavior, your GitHub token never reaches the agent’s sandbox — OpenComputer pulls only the linked directory at the exact commit in an isolated worker, and no repository code runs. A managed Flue build uses the same short-lived source-token boundary, then runs repository code only after the tokenless handoff described above.

Deploy from your machine

No repo needed — the CLI bundles a local agent directory and deploys it:

CLI

oc agent deploy                       # deploy ./ (the agent named in agent.toml)
oc agent deploy ./agents/issue-fixer  # a specific directory
oc agent deploy --no-activate         # stage a built-in runtime revision

Same as a repo push — handy for CI that isn’t GitHub, or trying a change before you commit.

Flue framework agents

A Flue agent ([runtime] family = "flue" in agent.toml) carries its instructions, tools, and packaged skills in code, so oc agent deploy builds and ships the Cloudflare app instead of reading prompt.md and the top-level skills/ directory:

CLI

oc agent deploy   # flue build --target cloudflare, upload, verify live Worker

The CLI creates the agent from agent.toml when needed, runs the locally installed Flue build, uploads the generated JavaScript modules, and waits for the exact live Worker to become stable. See Run Flue agents for the required app wiring and current deployment constraints.

Roll back and promote

Rollback and promote are the same primitive — set the active revision. Re-activate any earlier revision (rollback) or a staged one (promote):

await oc.agents.revisions.activate("agt_123", 3);

POST https://api.opencomputer.dev/v3/agents/agt_123/revisions/3/activate
Authorization: Bearer $OPENCOMPUTER_API_KEY

oc agent rollback 3

Instant — no rebuild. Running sessions are unaffected; new sessions use the newly-active revision.

The pointer-only rollback above applies to the built-in runtimes. It does not replace a Flue agent’s live Worker bytes. To restore a Flue build, check out the known-good source and run oc agent deploy again. Do not downgrade across an incompatible Flue Durable Object schema version.

Inspect

REST API

GET /v3/agents/agt_123/deployments?limit=50      # deployment history + opaque next_cursor
GET /v3/agents/agt_123/deployments/dep_123       # one attempt, timing, source, build, result
GET /v3/agents/agt_123/deployments/dep_123/logs  # durable chunks; resume with ?after=<cursor>
GET /v3/agents/agt_123/revisions                # revision history (newest first; active flagged)
GET /v3/agents/agt_123/revisions/5              # one revision + its skill file manifest
GET /v3/agents/agt_123/activations              # active-pointer audit log

GET /agents/:id also includes an active_revision summary (id, number, digest).

Skills

Skills — reusable instruction folders the agent loads when relevant — are part of a revision, so they’re deployed, versioned, and rolled back exactly like the prompt and model. Include them inline in a deployment (skills:[…], above), upload a .zip (PUT …/skills), or ship a skills/ directory from a repo. See the Skills page for the SKILL.md format, how skills are invoked, all three ways to add them, and limits.

Not yet supported

These are coming soon — a deployment that includes them is rejected today:

MCP servers (mcp.json)
Custom runtimes (a runtime/ directory)
Skills on codex agents — skills are claude-runtime only for now

Dashboard

The agent page in the dashboard keeps Deployments as the operational attempt history and Revisions as successful immutable results. Repository deployment detail includes its exact commit, phase, timing, build metadata, safe error summary, and persisted log.

Getting Started

Sandboxes

Browser Sessions

Durable Agent Sessions

Reserved Capacity

CLI

Guides

TypeScript SDK

Python SDK

CLI Reference

API Reference

Resources

Deployments & revisions

Revisions

Deploy

Staging vs activating

Deploy from a repo

Import a Flue repository

Link a built-in agent directory

Deploy from your machine

Flue framework agents

Roll back and promote

Inspect

Skills

Not yet supported

Dashboard

​Revisions

​Deploy

​Staging vs activating

​Deploy from a repo

​Import a Flue repository

​Link a built-in agent directory

​Deploy from your machine

​Flue framework agents

​Roll back and promote

​Inspect

​Skills

​Not yet supported

​Dashboard

Revisions

Deploy

Staging vs activating

Deploy from a repo

Import a Flue repository

Link a built-in agent directory

Deploy from your machine

Flue framework agents

Roll back and promote

Inspect

Skills

Not yet supported

Dashboard