> ## Documentation Index > Fetch the complete documentation index at: https://docs.orcapods.ai/llms.txt > Use this file to discover all available pages before exploring further. # Agent documents > The YAML or JSON file that orca agents create and orca agents update read: every field, what is validated locally, and what the server owns. > **Last updated: 2026-09-06** `orca agents create -f ` and `orca agents update -f ` take an agent document: a YAML or JSON description of an [agent profile](/concepts/profiles). 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 ```yaml agent.yaml theme={"dark"} 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 ``` ```bash theme={"dark"} 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](/concepts/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](/concepts/profiles#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://`, matching the entry's `name`. Points at a [Connected Apps](/concepts/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 ` instead. See [orca mcp](/cli/reference/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](/concepts/profiles#filesystem-policy) and [Storage](/concepts/storage). ### sandbox Runs the agent's tools inside a sandboxed workspace. `provider` is required when `sandbox` is present. See [Sandboxes](/concepts/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`: ```text theme={"dark"} 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 --json` prints the stored profile, which is itself a valid document: ```bash theme={"dark"} 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.