Sandbox reference
What a session sandbox in Orca Agent Engine guarantees - the filesystem layout, where an agent may write, what gets mounted where, and the per-session limits.
Every session runs its tool calls inside an isolated sandbox built from the session's environment. This page is the contract: the paths an agent can rely on, where each kind of resource lands, and what the platform caps.
What is installed in the sandbox - language runtimes, CLIs, package versions - comes from the container image your operator configures, not from Orca. Ask your operator which image a Workspace runs, or discover it from inside a session with bash. Nothing on this page depends on that choice.
Filesystem layout
| Path | What it is |
|---|---|
/mnt/session/outputs/ | Always writable. Files written here become session outputs and are collected when the session ends. It is the only writable root that publishes downloadable output. |
/mnt/session/uploads/<file_id>/ | Where an attached file is mounted. Read-only by default. |
/mnt/memory/<store-name>/ | Where an attached memory store is mounted, falling back to the store ID when the name is not a safe path segment. It is writable only for a read_write resource. Derived by the registry - a memory-store resource takes no mount_path. |
/workspace/<repo>/ | Where a GitHub repository is cloned. The last URL segment, minus any .git suffix. It is writable only for a read_write resource. |
/tmp | A fresh writable temporary filesystem per agent process. HOME points inside it. Scratch here is never indexed and is destroyed with the sandbox. |
The write policy permits the output root, explicitly read-write memory and repository resources, and ephemeral scratch. Everything else is mounted read-only. An agent that tries to write outside a permitted path gets:
write denied for <path>; user-downloadable files must be written under /mnt/session/outputs/Tell the agent where to put its work. A system prompt that says "write the report to /mnt/session/outputs/report.md" avoids a class of failure that otherwise surfaces as a confusing denial mid-run.
The check runs before the agent starts and fails closed: if the platform cannot establish the write policy, the session does not run.
Per-session limits
| Resource | Limit |
|---|---|
| Files | 100 in this build. Confirm with your operator before designing around a higher number - production may allow more. |
| Memory stores | 8 |
| GitHub repositories | 8 |
The registry rejects a duplicate mount_path only among memory_store resources and rejects every resource path that overlaps the reserved Skill root /workspace/skills. It does not generally compare file and repository paths. Before a session starts, though, the write policy rejects any overlap between writable roots - including the output root and a read-write memory or repository - and any writable/read-only overlap. Two read-only resource paths can still overlap, so choose non-colliding mount paths even when no write-capable resource is involved.
Installing packages
You cannot. An environment has a config.packages field and the
registry stores what you put in it, but no managed sandbox installs anything.
A non-empty packages list makes every session on that environment fail to start. The check
runs during sandbox setup, in every managed sandbox mode, before any install would happen; the
session emits session.error with type setup_failed and is left idle and resumable - it does not run without the packages, it does not run at all. On the default dialect that error type reads as unknown_error, so match on the failure to start rather than on the string.
The reason is ordering: install hooks run before resource and Skill roots are sealed, which would let an install leave a background process outside the agent's namespace. The field stays in the API for when runtimes can seal the filesystem first.
Nor can you supply your own image: the environment's image field is ignored under separate mode
and rejected under colocated by the same check. What a session gets is whatever the
operator-owned image already contains. If a session needs a tool that is not in it, that is a
conversation with your operator rather than something you can declare.
Resource limits
CPU, memory, and maximum session lifetime are deployment-level settings, not per-environment ones. There is no field on an environment or a session that raises them, and no API that reports them.
Ask your operator for the values a Workspace runs. If an agent is being killed part-way through long work, session lifetime is the first thing to check.
Network access
Sessions have no general-purpose web access by default, and the built-in web_fetch and web_search tools do not reach the model - see Tools. Give an agent network reach by declaring an MCP server that provides it.
An environment's networking configuration is accepted and stored but not enforced - see Environments. Do not rely on it to restrict egress. Treat whatever the sandbox can reach as reachable, and keep secrets in vaults so they never enter the sandbox in the first place.