Join our Discord Server
Collabnix Team The Collabnix Team is a diverse collective of Docker, Kubernetes, and IoT experts united by a passion for cloud-native technologies. With backgrounds spanning across DevOps, platform engineering, cloud architecture, and container orchestration, our contributors bring together decades of combined experience from various industries and technical domains.

Connect Orca to Docker Sandboxes over SSH: Parallel Agent Worktrees in an Isolated Sandbox

6 min read

Dark terminal window showing the command ssh demo.sbx with the title Connect Orca to Docker Sandboxes over SSH

Orca is a desktop app that runs several coding agents in parallel, each one in its own git worktree. Docker Sandboxes gives each agent an isolated microVM with its own network and credential controls. The new Connect Orca to a sandbox guide on docs.docker.com shows how to put the two together: Orca keeps the editor and diff views on your host, while the agents, terminals and git operations run inside a sandbox.

The interesting part is that there is no special plugin. Orca treats the sandbox as a normal SSH host, and the sbx CLI makes every local sandbox reachable at <name>.sbx. In this post we walk through the setup, explain how the managed SSH connection works under the hood, cover the one build dependency that trips up custom images, and look at where cloud sandboxes fit.

Prerequisites

  • Docker Sandboxes 0.37.0 or later. Both the Orca page and the Editor and app integrations page list this as the minimum.
  • The sbx CLI installed and signed in to Docker. SSH connections are only accepted while you have an active Docker login. See Get started and Install.
  • An OpenSSH client. macOS and most Linux distributions ship one. On Windows, install the OpenSSH client feature.
  • Orca installed on your host.
  • A model provider credential for the agent you plan to run, for example an Anthropic API key for Claude Code.

Note that the CLI reference marks sbx setup ssh as experimental, so its behavior can change between releases. Check the sbx setup ssh reference if something looks different on your version.

How SSH into a sandbox works

Before running commands, it helps to understand what you are connecting to. No SSH server runs inside the sandbox, and no TCP port is published. Instead, SSH terminates at the Docker Sandboxes daemon on your host. Running sbx setup ssh writes a managed block into ~/.ssh/config (or %USERPROFILE%\.ssh\config on Windows) that looks like this:

# >>> docker sandboxes (managed) >>>
Host *.sbx
  User _default_user_
  ProxyCommand "sbx" ssh proxy %n
  IdentityAgent none
  IdentityFile /dev/null
  IdentitiesOnly yes
  ControlMaster no
  ControlPath none
  UserKnownHostsFile "~/.ssh/sbx_known_hosts"
  KnownHostsCommand "sbx" ssh known-hosts %H
  StrictHostKeyChecking yes
# <<< docker sandboxes (managed) <<<

A few details in this block matter for any SSH based tool, Orca included:

  • ProxyCommand relays the SSH stream to the daemon over a local socket: a Unix domain socket on macOS and Linux, a named pipe on Windows. Nothing listens on the network.
  • No key pair. IdentityFile /dev/null and IdentityAgent none mean your SSH keys are never offered. Authentication is tied to your Docker login instead.
  • Host key checks stay strict. The KnownHostsCommand fetches the daemon key on each connection, so a rotated daemon key does not cause a host key mismatch.
  • User _default_user_ is a reserved name. It tells the daemon to run as the default user of the sandbox image, so your host username is never sent. Any other username is treated literally as a user inside the sandbox.
  • Host *.sbx is a wildcard. Apps cannot discover individual sandbox names from it, so you type the hostname, such as demo.sbx, by hand.

Do not edit this block yourself. Re-run the setup command instead; it is idempotent.

Step 1: Enable SSH and create an agent sandbox

Run the SSH setup once. It starts the daemon if needed and configures your SSH client:

sbx setup ssh

Orca only offers agents that it finds installed on the host it connects to. A sandbox does not start an agent on its own in this flow, so create the sandbox with the agent you want Orca to drive. From your project directory:

sbx create --name demo claude .

This creates a sandbox named demo for Claude Code with the current directory as its workspace. Sandbox names must be at least two characters and may use letters, numbers, hyphens and periods. Confirm it exists with:

sbx ls

Then prove that plain SSH works before involving Orca:

ssh demo.sbx

An interactive shell starts in the sandbox workspace, the same place sbx exec lands. If the sandbox is stopped, connecting starts it for you. Your workspace appears inside the sandbox at the same absolute path it has on the host, which is useful later when Orca or an editor asks you to pick a folder.

Step 2: Make sure remote terminals can build

This is the step most likely to cause confusion. Orca’s remote terminals depend on node-pty, which only ships prebuilt binaries for macOS and Windows. Inside a Linux sandbox it compiles from source, so the sandbox needs a C++ toolchain.

Docker-provided templates already include a compiler, so a sandbox created as above is ready. The problem shows up with a sandbox built from a custom base image that has no compiler. In that case Orca still connects, and files, git and the editor work, but remote terminals do not start. The proper fix is to add the toolchain to your image. As a stopgap, install it in the running sandbox:

sbx exec demo -- sudo apt-get update
sbx exec demo -- sudo DEBIAN_FRONTEND=noninteractive apt-get install -y build-essential

Everything after -- runs inside the sandbox. Setting DEBIAN_FRONTEND=noninteractive keeps apt from waiting on prompts. Remember that packages installed this way live only in that sandbox, so bake build-essential into the image for anything you plan to recreate.

Step 3: Add the sandbox as an SSH target in Orca

With SSH confirmed, configure Orca:

  1. Open Settings → SSH and select Add Target.
  2. Set the host to the sandbox hostname, for example demo.sbx.
  3. Set the username to _default_user_.
  4. Keep the default port and leave the identity file empty. The managed SSH config handles routing and authentication, so a key would only get in the way.
  5. Select Test, then Save.
  6. Create a worktree and choose the sandbox under Run on.

The first connection installs a small Orca relay inside the sandbox, so it takes a moment. Later connections reuse it and are faster. If Orca’s folder picker opens in the home directory (/home/agent) instead of your project, select the workspace path explicitly. For a sandbox without a host mount that uses a Docker-provided agent template, the workspace is /home/agent/workspace.

Step 4: Run agents and keep credentials on the host

Orca launches whichever agent you pick for a worktree. For new launches it pre-fills each agent’s permission bypass flag, such as --dangerously-skip-permissions for Claude Code. That matches how sbx run starts the same agents, and it is the reason the sandbox matters: the agent can act freely because the blast radius is the microVM, not your laptop.

Credentials should never be copied into the sandbox. Store them on the host instead:

sbx secret set anthropic

You are prompted for the value. When the agent calls the provider, a proxy on the host matches the request, looks up the stored credential and writes the auth header before forwarding it. The sandbox only ever sees a sentinel value. The credentials page also covers scoping a secret to one sandbox with --sandbox and pulling values from a password manager with --ref.

Local Sandboxes vs Cloud Sandboxes

The Orca guide is written for local sandboxes. Everything above, including <name>.sbx hostnames and the managed config, applies to sandboxes running through your local daemon. Cloud sandboxes use a different SSH configuration and address, and the docs point to the Connect with SSH section of the cloud usage page:

sbx --cloud setup ssh
sbx --cloud ls
ssh <sandbox-id>@sbx_cloud

Here you connect with the sbx_ prefixed ID that sbx --cloud ls prints, not the sandbox name, and the host is sbx_cloud. Cloud SSH honors the upstream proxy configured on your host. The Orca page does not document an Orca setup for cloud sandboxes, so treat any cloud target as something to test yourself rather than a supported recipe. Credentials also differ: the local secret store does not apply to cloud sandboxes, which have their own cloud credential setup.

Troubleshooting

  • Remote terminals never open, but files and git work. The sandbox image has no C++ compiler, so node-pty cannot build. Install build-essential as shown in Step 2, or add it to your base image.
  • Connection rejected. The daemon only accepts SSH while you have an active Docker login. Sign in again and re-run sbx setup ssh.
  • Hostname not found in an app picker. The *.sbx wildcard cannot be browsed. Type the full hostname, and create the sandbox first, because a plain <name>.sbx connection does not create one.
  • Agent missing from Orca’s list. Orca only offers agents installed in the target. Recreate the sandbox with the agent name, for example sbx create --name demo claude ..
  • Environment variables not visible inside. SSH does not forward client environment variables. The daemon accepts the request for compatibility but ignores the values. Use stored secrets or the sandbox’s own configuration instead.
  • Port forwarding refused. Forwarded connections are only allowed to loopback addresses inside the sandbox (localhost, 127.0.0.0/8, ::1). Keep the host side bound to 127.0.0.1 unless you really want the service reachable from other machines.

Key takeaways

  • Orca has no dedicated Docker Sandboxes integration. It connects to <name>.sbx as an ordinary SSH host after you run sbx setup ssh.
  • SSH terminates at the host daemon over a local socket. There is no SSH server in the sandbox, no open port and no key pair; access depends on your Docker login.
  • Use _default_user_ as the username, the default port, and no identity file.
  • Create the sandbox with the agent you want Orca to run, because Orca only lists agents installed in the target.
  • Custom images need a C++ toolchain for Orca’s remote terminals. Docker-provided templates already have one.
  • Keep API keys on the host with sbx secret set; the proxy injects them so the agent never holds the real value.
  • Cloud sandboxes use sbx --cloud setup ssh and ssh <sandbox-id>@sbx_cloud, a different path from the local guide.

References

Source guide: Connect Orca to a sandbox. Related pages: Editor and app integrations, sbx setup ssh CLI reference, sbx create CLI reference, Manage credentials, Use cloud sandboxes and Troubleshooting.

Have Queries? Join https://launchpass.com/collabnix

Collabnix Team The Collabnix Team is a diverse collective of Docker, Kubernetes, and IoT experts united by a passion for cloud-native technologies. With backgrounds spanning across DevOps, platform engineering, cloud architecture, and container orchestration, our contributors bring together decades of combined experience from various industries and technical domains.

Understanding AI Embeddings and Vector Search for Beginners

Explore the world of AI embeddings and vector search, learning how they transform massive data into actionable insights, driving intelligent systems.
Collabnix Team
9 min read
Join our Discord Server