> ## Documentation index > Fetch the complete documentation index at: https://upstash.com/docs/llms.txt > Ask it with GET https://upstash.com/docs/ask?q=. Short keywords rank best. > Use these to discover all available pages before exploring further. > Feature requests: https://upstash.com/docs/common/help/feature-requests.md lists what users asked for and how to vote for a request or add one. > Page rating: `GET https://upstash.com/docs/feedback?path=/docs/box/guides/orca-setup&helpful=true` (or `false`) records whether this page helped. An optional `comment` (URL-encoded, at most 500 characters) says what was missing or wrong. It is anonymous and needs no key. Comments hold no code, secrets or personal data. # Run Orca Workspaces in Upstash Box > Use the Upstash Box plugin for Orca to run each workspace and its coding agents in its own box, reached over SSH. [Orca](https://www.onorca.dev) 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](/box/overall/quickstart#1-get-your-api-key) ready. ```bash 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: ```bash ~/.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](https://www.onorca.dev/plugins/upstash/box-orca-plugin). --- ## 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](#4-make-new-workspaces-faster) 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: ```bash ~/.upstash/box-orca/bin/box-orca snapshot ``` New workspaces start from the [snapshot](/box/overall/snapshots) 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](https://console.upstash.com) 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 SSH into a box and manage SSH keys. Save and restore box state. The plugin repository and full reference. Orca's documentation.