Orca sandbox: run each Orca workspace in its own CreateOS microVM

To give Orca a sandbox, sign in with createos login, install the CreateOS Sandbox plugin in Orca, and pick CreateOS Sandbox under Run on > Per-Workspace Environment. Each workspace then gets its own microVM. Orca connects to it over SSH and runs your coding agent there, so installs, builds and test runs stay off your laptop.

It is for developers who run several coding agents side by side in Orca. CreateOS Sandbox gives each workspace a Firecracker microVM with its own guest kernel, root filesystem and network identity.

Orca is a separate open source project. The CreateOS Sandbox plugin for Orca is maintained by CreateOS and is not a product of the Orca project.

Key takeaways

The plugin registers one Orca recipe that creates and destroys a microVM per workspace.
The recipe pushes your checkout into the sandbox, so no git token reaches it and private repositories work.
The project must be a git repository with a remote, or workspace creation fails at the last step.
The recipe sets no egress rules, so outbound network access is open until you set an allowlist.

What does the CreateOS recipe change about an Orca workspace?

It moves the whole workspace, agent included, onto a disposable VM-isolated box. Orca describes itself as "the place for working with a fleet of agents" (Orca on GitHub). Its per-workspace environments boot each worktree from a recipe, and you bring the provider (Ways to run Orca).

The CreateOS recipe is one such provider. Per the plugin README, create makes a microVM from the devbox:1 image and wires SSH through the CreateOS gateway. It then uploads your working tree, uncommitted edits included, and checks it out on a branch named after the workspace. Destroy removes the sandbox and its ~/.ssh/config entry. For background, read what an AI agent sandbox is.

How do I set up an Orca sandbox on CreateOS?

Four steps take you to a first workspace on a microVM. You need Orca 1.4.0 or later (the version the plugin manifest requires), git and ssh on your PATH, and a CreateOS account.

Step 1: How do I install the createos CLI and sign in?

Install the CLI, then run createos login. Copy the install command from the Prerequisites section of the docs. For CI or headless use, export CREATEOS_API_KEY instead of signing in.

Your credentials stay on your machine and create the sandbox. The agent's provider credentials belong inside the workspace.

Step 2: How do I check the prerequisites?

Run the doctor check:

createos sandbox setup orca --doctor

It checks your sign-in and that git and ssh are on your PATH, and changes nothing.

Step 3: How do I install the plugin in Orca?

Install it from a git URL inside Orca. Open Settings > Plugins > Install from git URL and paste the URL from the Install section of the docs. Keep the version tag on the URL. The docs also list createos sandbox setup orca; for now run it only with --doctor, because without the flag it prints an older manual install route.

Approve the plugin when Orca asks, then turn on the Cloud VM setting, which Orca lists under Settings > Experimental.

Step 4: How do I create a workspace on a CreateOS sandbox?

Create a workspace and pick CreateOS Sandbox under Run on > Per-Workspace Environment. The project needs a git remote, because Orca compares remote identities to match the sandbox checkout to your project. A repository with no remote fails with Imported folder does not match the selected project identity. Add one with git remote add origin <your-repository-url>.

How do I get Claude Code or Codex inside the workspace?

Name the agents in CREATEOS_AGENTS before you create the workspace. Nothing is installed by default:

CREATEOS_AGENTS=claude,codex

Accepted names are claude, codex, cursor (which installs cursor-agent), opencode and pi. An unknown name fails before any sandbox is created. An agent already on the image is skipped, and the devbox:1 image already carries all five, per the image list.

On other images, agents install from vendor scripts that are not pinned or checksum-verified. To control exactly what you get, build an image and point CREATEOS_ROOTFS at it.

Can an Orca workspace sandbox reach the internet?

Yes, by default. The recipe sets no egress rules, and a CreateOS sandbox with an empty rule list can reach any external host. Once any rule is set, only the listed destinations pass. Everything else is dropped in-kernel on the host, outside the VM, so code inside cannot change the policy (Limits and defaults).

To restrict a workspace, replace its allowlist with the Egress API. Include the hosts your agent's model provider and package managers need. Inbound is closed unless you enable ingress. For why the boundary sits outside the guest, read how CreateOS enforces egress outside the VM.

What are the limits of the CreateOS recipe for Orca?

The main limits are destroy-and-recreate, upload size and your account's caps. They come from the plugin README and the Limits page.

No suspend or resume. SSH does not reliably come back after a sandbox resume, so the recipe declares neither phase. Every workspace is destroy-and-recreate.
Upload size. Working trees of roughly 400 MB and above, after .gitignore exclusions, can fail with a 503 during upload.
Default shape. Each workspace defaults to 4 vCPU and 8 GB. Your account sets the largest shape it can create, so set CREATEOS_SHAPE to a smaller one if creation is refused.
Sandbox cap. Each open workspace is one sandbox, and your account caps how many exist at once. A create over the cap fails and is not queued.
Disk. The recipe uses the default 10 GiB disk and has no setting to raise it.
No GPUs. No GPU shapes are offered.

If a create fails, Orca shows Couldn't create worktree with the real reason in the log panel below. The recipe destroys the sandbox it made. Check for leftovers with createos sandbox list.

When do I not need this?

If your laptop handles the builds and you trust the agents, Orca's local worktrees are enough. If you already run a long-lived machine you control, Orca connects to SSH targets directly. Use the CreateOS recipe when each workspace should get a fresh box with its own kernel.

Common questions

How do I run an Orca workspace in a sandbox?

Sign in with createos login, install the CreateOS Sandbox plugin from Orca's Settings > Plugins > Install from git URL, and turn on Cloud VM. Then pick CreateOS Sandbox under Run on > Per-Workspace Environment. Each workspace gets a microVM with its own guest kernel.

Does the CreateOS recipe for Orca support suspend and resume?

No. SSH does not reliably come back after a sandbox resume, so the recipe declares neither phase. Every workspace is destroy-and-recreate, and deleting the workspace destroys its sandbox.

Why does Orca say the imported folder does not match the selected project identity?

The project has no git remote. Orca compares git remote identities to confirm the checkout on the sandbox is the same project, and a repository with no remote can never match. Add a remote with git remote add origin, then create the workspace again.

Does my git token reach the CreateOS sandbox?

No. The recipe packs your working tree and pushes it into the sandbox, so no git token reaches the VM and private repositories work with no extra setup.

Can a CreateOS sandbox for Orca reach the internet?

Yes. The recipe sets no egress rules, so outbound access is open. Once you set any rule through the Egress API, only listed destinations pass and everything else is dropped in-kernel on the host, outside the VM.

Which coding agents can the Orca recipe install?

Set CREATEOS_AGENTS to any of claude, codex, cursor, opencode or pi, comma-separated. Nothing is installed by default, an unknown name fails before a sandbox is created, and an agent already on the image is skipped.

Next step

The Orca integration docs hold the CLI install command and the plugin URL. Open the CreateOS Sandbox docs for Orca and create your first workspace on a microVM.

About CreateOS

CreateOS runs AI agents and the code they write. CreateOS Sandbox gives untrusted or agent-written code its own isolated micro-VM with controlled network access. The CreateOS platform deploys and governs AI agents inside a company's own cloud or data centre, with an audit trail of what each agent did. Start at createos.sh.

Orca sandbox: run each Orca workspace in its own CreateOS microVM