Run Orca Workspaces in Upstash Box

Orca runs coding agents side by side, each in its own Git worktree. The Upstash Box plugin gives every Orca workspace its own box: Orca creates the box when you create the workspace, connects to it over SSH, and deletes it when you delete the workspace.

Your agents keep working in the box when you close Orca, and Orca reattaches when you open it again.

1. Set up#

Needs Orca 1.4.245 or newer, Node.js 20 or newer, git, and ssh. Have an Upstash Box API key ready.

npx -y github:upstash/box-orca-plugin#v0.1.1 setup

Setup asks for your API key, then:

• creates an SSH key and adds it to your Upstash account
• trusts the Upstash Box SSH gateway’s host key
• installs the plugin’s helper at ~/.upstash/box-orca/bin/box-orca

Check it with:

~/.upstash/box-orca/bin/box-orca doctor

2. Install the plugin#

In Orca, open Settings > Experimental and turn on Cloud VM.

Then open Settings > Plugins, choose Install from git URL, and paste:

https://github.com/upstash/box-orca-plugin.git#v0.1.1

The plugin is also listed in Orca’s community plugins.

3. Create a workspace#

Create a workspace on a project with a Git remote. Under Run on, pick Upstash Box in Per-Workspace Environment.

The plugin creates a box, uploads the commit Orca selected from your machine, and checks out the workspace branch at /workspace/home/repo. No Git token is sent to the box for this.

The first time Orca connects to a new box, it installs its remote runtime, which can take a few minutes. Step 4 removes that wait.

Claude Code and Codex are already installed in the box. Run them from the workspace’s terminal, and log in the first time.

Deleting the workspace in Orca deletes its box.

4. Make new workspaces faster#

Snapshot a box Orca has already set up, so new workspaces start with Orca’s runtime installed and your agents logged in:

1. Create one workspace and wait until it connects.

2. In its terminal, log in to your agents (claude, codex).

3. Run:

   ~/.upstash/box-orca/bin/box-orca snapshot

New workspaces start from the snapshot and are ready in under a minute. Each one still gets its own Orca identity and a fresh checkout.

The snapshot copies that box’s home directory, so anything else in it comes along, such as shell history. After you update Orca, run snapshot again once a new workspace has connected.

5. Push to GitHub#

To push and open pull requests from a workspace, the box needs a GitHub login. Either:

• Connect GitHub in the Upstash Console under Box > Settings > GitHub. Every new box gets your GitHub credentials for git and gh.
• Or run gh auth login and gh auth setup-git in the workspace’s terminal. Do it before taking a snapshot so later workspaces have it too.

Next steps#