Self-Host Orb and sandboxed.sh with Docker

Understand the Orb and sandboxed.sh architecture

Orb and sandboxed.sh are related but distinct parts of the deployment. Orb provides the macOS and iOS interfaces. The project formerly called sandboxed.sh is now the backend to those clients. According to the current Orb documentation, the Rust backend owns projects, missions, event history, and remote-node coordination. Closing a client therefore does not make the backend disposable.

Orb separates where a user reads and steers a mission from where its agent executes. The currently documented execution modes are:

The v0.12.0 release used as the baseline in this tutorial includes the backend changes described in that release, including updated mission state handling and storage migrations. The public documentation has continued to evolve beyond that release. Pinning commit 33c0345 makes the deployment reproducible, but it also means that features documented only on a newer master revision may not exist in this baseline.

Prepare the Docker host

Use a Linux host that can remain available whenever Orb clients need the backend. This guide follows the repository's Docker path and does not mix it with the separate native Linux installation. You need Git, Docker Engine, and the Docker Compose plugin. Your account must be authorized to run Docker commands.

Check the tools before cloning the project:

git --version
docker version
docker compose version

Docker privileges are security-sensitive. Membership in a group that can control the Docker daemon commonly grants broad control over the host. Do not give routine Orb users shell access to the Docker account, and do not expose the Docker daemon through Localtonet.

Also prepare:

• A dedicated deployment directory with restricted access.
• Sufficient storage for images, backend data, logs, projects, and any server-side workspaces you enable.
• A backup destination that is not the same Docker volume or physical disk as the live deployment.
• An authorized Orb account or bootstrap path defined by the selected release.
• A Localtonet client device that can reach the final client-facing host address and port.

Install the pinned Orb release with Docker Compose

The Orb repository contains the root Dockerfile, docker-compose.yml, .env.example, and INSTALL.md files used by the Docker workflow. The following checkout pins v0.12.0 at commit 33c0345 instead of silently deploying a moving development branch.

git clone https://github.com/Th0rgal/orb.git
cd orb

git fetch --tags
git checkout v0.12.0
git rev-parse --short HEAD
git status --short --branch

cp .env.example .env
chmod 600 .env

docker compose config --quiet
docker compose config --services
docker compose config --volumes
docker compose config --images

docker compose up -d --build

docker compose ps
docker compose logs --tail=200

Keep the initial terminal output. It is useful when comparing a later restart or upgrade. A container that repeatedly changes from running to restarting is not a successful installation, even if docker compose up returned without an immediate shell error.

Configure required values and inspect the actual deployment

Separate core settings from optional providers

Use the checked-out .env.example and INSTALL.md as the configuration schema for v0.12.0. Do not copy environment names from a newer master revision into the release without checking whether that release recognizes them. Conversely, do not delete an unfamiliar release variable merely because it is absent from a newer article.

A value is mandatory for this deployment when the pinned installation instructions require it, the Compose interpolation marks it as required, or startup fails with an explicit missing-setting error. Optional provider integrations should remain unset until the server, sign-in, and persistence checks pass.

Current Orb documentation explains that SANDBOXED_OAUTH_OWNER=cli-proxy lets CLIProxyAPI own OAuth token refresh for supported provider accounts, avoiding refresh-token races between processes. That setting affects model inference routing and OAuth ownership. It does not create an Orb backend account, sign in a ChatGPT browser profile, or create a Cursor Cloud API account.

Identify the client-facing service and published port

Do not assume a port number from a different release. Use the active Compose project to print the real host mappings:

docker compose ps
docker compose ps -q | xargs -r docker inspect \
  --format '{{.Name}} {{range $port, $bindings := .NetworkSettings.Ports}}{{$port}} -> {{range $bindings}}{{.HostIp}}:{{.HostPort}} {{end}}{{end}}'

The first command associates Compose service names with their state and published ports. The second distinguishes container ports from host addresses and ports. Record the mapping for the service intended to receive Orb client traffic.

If no host port appears, the service is not directly published by Docker. Check the pinned Compose file for a bundled reverse proxy or another documented entry point. Do not create an arbitrary port mapping until you understand which service provides authentication and client routing.

Inspect mounts and persistent volumes

List the declared volumes and then inspect the running containers:

docker compose config --volumes

docker compose ps -q | xargs -r docker inspect \
  --format '{{.Name}}{{range .Mounts}}{{printf "\n  %s: %s -> %s" .Type .Source .Destination}}{{end}}'

This shows the actual source and destination of named volumes and bind mounts. Mark a location as persistent if it contains the backend's projects, missions, event records, account state, configuration, or workspaces that must survive image replacement. Temporary build caches do not necessarily require the same backup treatment.

Inspect whether a container mounts /var/run/docker.sock or another Docker daemon endpoint. If it does, treat that container as a host-privileged control component. Compromise of that component may become compromise of the Docker host.

Check health checks and dependencies

Use Compose status to see whether a health state is reported:

docker compose ps
docker compose ps -q | xargs -r docker inspect \
  --format '{{.Name}} health={{if .State.Health}}{{.State.Health.Status}}{{else}}not-declared{{end}} restart={{.RestartCount}}'

A reported healthy result is useful, but it is not a substitute for an Orb sign-in and persistence test. A health check can prove that a process responds while an authentication, migration, storage, or event-stream path remains broken.

Verify the server, sign-in, and persistence locally

Test the discovered endpoint

Convert the published mapping into a local URL. If Docker reports a plain HTTP mapping such as 127.0.0.1:PUBLISHED_PORT or 0.0.0.0:PUBLISHED_PORT, test that exact port from the Docker host:

curl --fail --show-error --location --verbose \
  http://127.0.0.1:PUBLISHED_PORT/

Replace PUBLISHED_PORT with the value printed by Docker. If the pinned deployment documents HTTPS at the local entry point, use its documented HTTPS URL instead of changing the scheme merely to make the command succeed. Certificate validation failures should be resolved according to the deployment's TLS design, not hidden with a permanent insecure option.

A redirect or authenticated application response can be valid. A response from an unrelated dashboard, database console, or development server is not. Watch the Compose logs while making the request:

docker compose logs --follow

Stop log following with Ctrl+C. This does not stop the containers.

Bootstrap authentication and sign in

The documented Orb client workflow is to run the sandboxed.sh backend, open Orb, enter the server URL, and sign in. The supplied v0.12.0 evidence does not expose a release-specific username, password, invitation command, or fixed default credential. Do not invent one and do not search logs for a reusable password unless the pinned installation instructions explicitly direct that procedure.

Complete the account bootstrap defined by the checked-out release's INSTALL.md or first-run interface. Then enter the locally reachable server URL in Orb and sign in. A valid acceptance test should establish all of the following:

• An unauthorized request does not reveal project or mission data.
• An authorized Orb client can sign in without a repeated authentication loop.
• The client loads server-backed project views.
• The backend logs show requests reaching the expected application service.

Create a first project and mission

In Orb, create a small test project and confirm that it appears after refreshing or reconnecting the client. Then choose one execution mode whose prerequisites are already available. For example, a local Mac run requires an installed local harness and its own login. A private-cloud run requires the target machine and workspace to be configured. Provider-backed modes require the relevant provider connection.

Launch a harmless first mission, inspect its transcript, and send a follow-up. This tests more than the landing page because it exercises server records and the selected execution path. Do not grant broad source-code, credential, or production-system access merely to complete this check.

Test persistence across restart

Restart the Compose services without deleting volumes:

docker compose restart
docker compose ps
docker compose logs --tail=200

Sign in again and verify that the test project, mission, and transcript still exist. If they disappear, stop and correct the storage configuration before using the server for important work.

A stronger lifecycle test stops and recreates the containers while retaining declared volumes:

docker compose down
docker compose up -d
docker compose ps

Do not add --volumes to the shutdown command unless you intentionally want to delete Compose-managed volumes. After recreation, repeat the sign-in and project checks.

Expose the verified Orb endpoint with Localtonet

For a client-facing endpoint verified as ordinary local HTTP, use a Localtonet HTTP tunnel. Our client establishes an outbound connection to a Localtonet relay server, so this workflow does not require inbound router port forwarding, a public IP address, VPN setup, or an inbound firewall change.

If the local entry point is actually HTTPS or another TLS service, do not describe it as HTTP. Confirm where TLS terminates and use the compatible Localtonet tunnel family. The steps below assume your verified Orb target is an HTTP service at a local IP address and published host port.

The current workflow is also described in the Localtonet HTTP tunnel documentation.

Verify from a genuinely external network

Do not test only from the Docker host or the same Wi-Fi network. Disable Wi-Fi on a mobile device and use cellular connectivity, or test from another independent internet connection. Open the Localtonet URL and confirm that the expected sign-in boundary appears.

Next, enter the public URL in Orb, sign in, open the test project, inspect the previous mission, and perform a small authorized write operation such as adding a follow-up. Confirm that the change remains visible after reconnecting. Review backend logs during the external test:

docker compose logs --follow

A browser page alone is not sufficient. Orb may use API requests or long-lived event streams that a simple root-page request does not exercise. The client workflow is the meaningful test.

Harden the host and agent execution boundary

Self-hosting an agent system requires more than protecting its web login. A coding agent can receive instructions, inspect workspaces, execute tools, modify files, and make network requests according to the permissions of its execution environment. Backend compromise and workload compromise can therefore have consequences beyond disclosure of a transcript.

Protect Docker and the control plane

Do not publish a Docker TCP endpoint or tunnel /var/run/docker.sock. If the Orb deployment mounts the socket into a management component, restrict who can alter that container, its image, its environment, and its mounted configuration. Use a dedicated host or virtual machine so that a compromise does not expose unrelated services.

Constrain agent workspaces

Give each execution environment only the files required for its task. Exclude password stores, SSH directories, cloud configuration, browser profiles, production environment files, and unrelated repositories. Review symlinks as well as direct mounts because a workspace path can otherwise lead outside its intended directory.

Orb documents private-cloud runs in host directories or isolated systemd-nspawn containers with cgroup resource caps. Resource caps reduce the effect of runaway CPU or memory use, but they do not automatically make arbitrary code trustworthy. Filesystem permissions, network policy, credentials, kernel exposure, and control-plane privileges remain relevant.

Keep integrations separate

Provider OAuth, API keys, backend accounts, cloud-agent sessions, and machine credentials serve different purposes. A provider token should not be reused as an application secret. A Localtonet device token should not be stored in the Orb environment file. A machine SSH key should not be copied into every mission workspace.

Log enough information to investigate failed authentication, startup, provider, and mission events, but avoid storing raw secrets or complete authorization headers. Restrict access to Compose logs because applications and third-party tools may occasionally write sensitive values during errors.

Back up, restore, restart, and upgrade safely

Routine status, logs, and restart commands

docker compose ps
docker compose logs --tail=200
docker compose restart
docker compose ps

Diagnose local service health before changing Localtonet. If the local Orb URL works but the public URL fails, inspect the Localtonet client and tunnel. If the local URL also fails, resolve the Docker or backend problem first.

Stop without deleting persistent data

To stop and remove the Compose containers and network while retaining declared volumes:

docker compose down

To start the same pinned deployment again:

docker compose up -d
docker compose ps

Avoid docker compose down --volumes during routine maintenance. That option requests deletion of Compose-managed volumes and can destroy backend state.

Back up the deployment

First use the mount-inspection command from the configuration section to identify every persistent named volume and bind-mounted data directory. Back up:

• The persistent backend data that contains projects, missions, events, account state, or migrations.
• Any durable workspaces that your recovery policy requires.
• The deployment's configuration and a protected copy of required secrets.
• The exact Git revision and container image identifiers used by the deployment.

For a consistent offline backup, stop the application before copying its persistent data:

docker compose stop
docker compose ps

Copy each inspected bind-mounted directory or export each named volume with your organization's tested Docker volume backup procedure. The exact archive command depends on the actual source paths and volume names printed by this deployment, so do not substitute a guessed volume. Restart after the backup:

docker compose start
docker compose ps

Test restoration

A backup is not proven until it restores. On an isolated host, check out the same commit, restore the protected environment configuration and persistent data to their corresponding paths or volumes, and start Compose. Then sign in and verify the test project, mission transcript, and execution configuration.

Do not perform the first restoration test over the live data set. A wrong mount target can cause the application to initialize empty storage, which may look like a successful startup while all expected records are absent.

Upgrade deliberately

Record the current state before changing versions:

git rev-parse HEAD
docker compose ps
docker compose images

Back up persistent data and configuration, then fetch the intended tag:

git fetch --tags
git checkout NEW_VERIFIED_TAG
docker compose config --quiet
docker compose build
docker compose up -d
docker compose ps
docker compose logs --tail=200

Replace NEW_VERIFIED_TAG only with a release you have reviewed. Read its release notes for migrations, renamed environment variables, changed mounts, or client compatibility requirements. Do not use an unpinned development branch as an unattended production upgrade strategy.

After upgrading, repeat the full local acceptance test before enabling remote access: endpoint response, sign-in, project loading, persistence, and one small mission. Then start or retest the Localtonet tunnel.

Troubleshoot Docker, Orb, and Localtonet systematically

Compose reports a missing variable

Confirm that .env was created from the .env.example included in the checked-out release. Run docker compose config --quiet again. Do not solve the error by assigning a random value to a secret, database location, public URL, or authentication setting.

A service exits or restarts repeatedly

Run docker compose ps and inspect docker compose logs --tail=200. Start with the first fatal error rather than later connection failures. Common categories include invalid configuration, inaccessible mounts, failed migrations, missing dependencies, and occupied ports.

The service runs, but no host port is listed

The container may be reachable only inside the Compose network, or another service may be the intended reverse proxy. Inspect docker-compose.yml at the pinned revision and identify the documented client entry point. Do not tunnel an internal service merely because it responds inside Docker.

The endpoint works on the host but not on another LAN device

A mapping bound to 127.0.0.1 is local to the Docker host. That is compatible with a Localtonet client running on the same host. A Localtonet client on another machine needs a backend address reachable from that machine and permitted by local firewall policy.

Orb reaches the server but cannot sign in

Confirm that the client is using the intended backend URL and not an unrelated web service. Review authentication-related backend logs and the account bootstrap instructions for the pinned revision. Keep the service private while fixing account, URL, clock, or configuration problems.

Projects disappear after a restart

Inspect the container mounts and compare them with the locations that hold backend state. Data may have been written to an ephemeral container layer, or a bind mount may point at the wrong empty directory. Stop creating important projects, correct the mount, restore a tested backup if available, and repeat the recreation test.

The public Localtonet URL does not open

Verify the local URL first. Then confirm that the selected Localtonet client is connected, the tunnel has been started, and its target IP address and port match the Docker mapping. Creating a tunnel alone does not make it active.

The public page opens, but Orb does not synchronize

Enter the public URL exactly, including its HTTPS scheme and any required path. Watch the backend logs during the client attempt. A root-page response does not prove that application APIs or long-lived streams are functioning.

A provider or harness fails after projects load correctly

Treat this as a later integration failure. Verify the selected execution placement, harness installation, provider account, model access, workspace, and remote-node registration. Do not rebuild the backend or change the tunnel solely because one provider fails while server-backed projects remain available.

Frequently asked questions