Agent documents

Last updated: 2026-09-06

orca agents create -f <path> and orca agents update -f <path> take an agent document: a YAML or JSON description of an agent profile. YAML is a superset of JSON, so one parser reads both; the file extension does not matter. Pass - to read the document from stdin. The CLI validates the document’s shape before anything is sent, so a typo comes back as a field-level message rather than a 400 from the server. Values the server owns, such as whether a model id or skill name exists, are checked server-side.

Example

agent.yaml

name: support-bot
runtime: vercel
model: anthropic:claude-sonnet-4-6
systemPrompt: |
  You answer support questions for Orca. Be concise.
  When you do not know, say so and point to the docs.
skills: [orca-docs]
tools: ["@default", "web_search", "web_extract"]
mcpServers:
  - name: docs
    transport: http
    url: https://mcp.example.com/docs
    headers:
      Authorization: Bearer example
fs:
  read: ["/datasets/**"]
  write: ["/shared/{self}/**"]
sandbox:
  provider: e2b
  template: base-python
  resources: { cpu: 1000, memoryMB: 1024 }
workerMode: sandbox
workerSubstrate: daytona

orca agents create -f agent.yaml
orca agents update -f agent.yaml          # target is the name in the file
orca agents update old-name -f agent.yaml # rename old-name to the name in the file

Fields

Field	Type	Required	Notes
`name`	string	yes	Unique within the tenant. Trimmed
`runtime`	string	yes	One of `pi`, `vercel`, `claude`, `codex`, `marlin`. The legacy value `general` is accepted with a warning and imported as `vercel`
`model`	string	no	Model id in the form the runtime expects, for example `anthropic:claude-sonnet-4-6` for `vercel` and `marlin`. The server rejects unknown or unpriced models
`systemPrompt`	string	no	Injected as the system message. Trimmed
`skills`	list of strings	no	Skill names to attach. See Skills
`tools`	list of strings	no	Tool selectors: named tools, `@bundle` sentinels, or `prefix_*` wildcards. Empty or omitted means the default safe toolkit. See tool selectors and `orca bundles`
`mcpServers`	list of objects	no	Per-agent MCP servers, see below
`fs`	object	no	Extra filesystem grants and denies, see below
`sandbox`	object	no	Sandboxed workspace, see below
`workerMode`	string	no	`static` (the default; omitted on the wire) or `sandbox`, which boots a per-session worker. Any other value is an error, not a warning, so a sandbox request is never silently downgraded. `runtime: marlin` requires `sandbox`
`workerSubstrate`	string	no	Where a sandbox worker boots: `e2b`, `daytona`, `docker`, or `process`. An unrecognized name warns but is sent, since the runner decides what it serves. Dropped with a warning unless `workerMode` is `sandbox`
`workerImage`	string	no	Substrate-specific image for the sandbox worker. Dropped with a warning unless `workerMode` is `sandbox`
`id`	string	no	Server-assigned profile id. Leave it out on create; harmless on update

Any other top-level key produces a warning naming the key and is not sent. With --strict, warnings become errors and the command exits 2.

workerMode, workerSubstrate, workerImage, and catalog ref entries are accepted from the next release after cli-v0.5.0. On cli-v0.5.0 itself they are dropped with an “unknown key” warning; set them from the dashboard or the API until you update.

mcpServers

Each entry attaches one MCP server to the agent. Names must be unique within the document, and runner is reserved. An entry is either an inline server (transport and url) or a catalog reference (ref), never both.

Field	Type	Required	Notes
`name`	string	yes	Tool prefix for the server
`transport`	string	inline only	`http` or `sse`
`url`	string	inline only	Absolute `http` or `https` URL
`headers`	map of string to string	no	Sent on every request. Omitted when empty. Not allowed on a `ref` entry
`ref`	string	ref only	Exactly `catalog://<name>`, matching the entry’s `name`. Points at a Connected Apps grant the runtime resolves at session time
`optional`	boolean	no	On a `ref` entry, marks a dependency the agent can run without

To share a server across agents, register it once with orca mcp add and attach it with orca mcp attach <agent> <name> instead. See orca mcp.

fs

Every agent already has /agents/{self}/** with read, write, and delete. fs adds to that.

Field	Type	Notes
`read`	list of globs	Additional read grants
`write`	list of globs	Additional write grants
`delete`	list of globs	Additional delete grants. Defaults to `write` server-side when omitted
`deny`	list of globs	Hard overrides that win over any grant
`allow_mounts`	list of prefixes	Explicit mount allowlist for the VirtualFS lease. Derived from the globs when omitted

Empty lists are dropped. See Filesystem policy and Storage.

sandbox

Runs the agent’s tools inside a sandboxed workspace. provider is required when sandbox is present. See Sandboxes.

Field	Type	Notes
`provider`	string	Sandbox provider, for example `e2b` or `daytona`
`template`	string	Provider-scoped image or template id
`resources`	object	Any of `cpu`, `memoryMB`, `diskMB`, `timeout`, all numbers
`env`	map of string to string	Environment variables for the sandbox
`idleTimeout`	number	Idle time before the sandbox is reclaimed, in nanoseconds

Unknown keys inside mcpServers[], fs, sandbox, and sandbox.resources also warn rather than fail.

Validation messages

Fatal problems are listed together under invalid agent document and exit 2:

orca: invalid agent document
  runtime is required and must be one of: pi, vercel, claude, codex, marlin
  mcpServers[0].transport must be "http" or "sse"

Other usage errors from the loader: a missing file, an empty file or empty stdin, and a document that fails to parse as YAML (the first line of the parser’s message is included).

Round-tripping

orca agents get <name> --json prints the stored profile, which is itself a valid document:

orca agents get support-bot --json > support-bot.json
# edit
orca agents update -f support-bot.json

The stored profile includes id and server-computed fields. The CLI warns about and drops the ones it does not model (such as workerPlacement), so the file imports, but do not combine a round-tripped file with --strict.

Verified against orca-cli cli-v0.5.0 (src/lib/profile-schema.ts). The same validator runs in the dashboard’s YAML import.

Using the CLI

Command reference

Agent documents

Example

Fields

mcpServers

fs

sandbox

Validation messages

Round-tripping

​Example

​Fields

​mcpServers

​fs

​sandbox

​Validation messages

​Round-tripping

Example

Fields

mcpServers

fs

sandbox

Validation messages

Round-tripping