Connected Servers: install and pair

To connect your own server for coding agent sandboxes you need a machine with Docker, three commands, and a pairing code from the web app. The machine becomes a Connected Server of your organization: every member launches sessions on it, and it never bills. A laptop, a workstation under a desk or a box in the office all work the same way.

The three commands

curl -fsSL isolation.cloud/server/install | sh
isolation-server up
isolation-server connect <code>

The installer puts one small script, isolation-server, on your PATH. The server itself is three Docker images from a release channel: ghcr.io/isolation-labs/server (the control layer), ghcr.io/isolation-labs/doorman (views, ssh and workspace sync) and the unmodified OpenSandbox runtime. No root is needed for any step.

Requirements. A running Docker with the compose plugin: Docker Engine on Linux, or Docker Desktop on macOS. On Windows, self-hosting runs inside WSL 2 only — the command is a bash script and the sandboxes need Linux's Docker socket. Docker Desktop with Enhanced Container Isolation turned on (a Business-plan setting an administrator can enforce) is not supported: it refuses the Docker socket mount the runtime needs, and isolation-server up says so. For anything beyond trying it out, a Linux host with Docker Engine is what the sandboxes want. The images are licensed under the Isolation EULA; the first up says so once.

What isolation-server up does

up reads the channel's manifest (which images, pinned by digest, and which compose template), pulls them and starts three containers that share one network namespace and restart with Docker:

• Everything persistent lives in one Docker volume, isolation-server-data: the server's configuration and master token, the pairing, the session and view registries, sealed secrets, the runtime's configuration and its database. The containers are disposable; the volume is not. isolation-server down keeps it, isolation-server down --purge deletes it after asking.
• The runtime is upstream OpenSandbox, its API reachable only inside that namespace with a key up mints. Sandboxes are sibling containers on your Docker, which is why the Docker socket is mounted — the same trust a source install had on the host.
• The doorman owns the one published port, 127.0.0.1:8090, and the ssh door (127.0.0.1:2200 by default; isolation-server ssh changes it). Isolation Cloud reaches the box through its tunnel, never through the port.

When it finishes, up prints that the server is healthy and which release it runs. isolation-server status and isolation-server logs -f show it afterwards; every later up first applies a newer release from the channel when there is one, and isolation-server update does that on its own, with a health check and a rollback to the previous pins if the new release does not come up.

Pairing with a code

Open the Servers page and choose New Connected Server. The dialog shows a short code and waits. On the machine, run isolation-server connect <code>. The code works once, expires within minutes, and is redeemed by the machine itself: its reply is that server's own credential, which never travels through your browser. Whoever holds a code can add a machine to the organization, which is why only an Owner or Admin can mint one, and why the /pair chat command answers in a direct message only. Pairing against a deployment other than app.isolation.cloud takes --backend <url>, which the dialog adds to the command for you.

During connect the server dials its private tunnel and starts its heartbeat; ssh into its sessions goes through the doorman's own door on the machine, no bastion in between. From then on it has no public address; tunnels, the doorman and what is public explains what that means.

The heartbeat and the green dot

A paired server phones home every 60 seconds (every 10 seconds while it warms up) with its version and machine id. Each beat makes Isolation Cloud probe the server back over the private tunnel and record the verdict, so the dot on the Servers page is verified from outside rather than assumed: amber while the first probe is pending, green while the last verified beat is fresh, red once no beat has arrived for 150 seconds. A graceful shutdown sends a final offline beat so the dot flips at once instead of waiting for the lapse. If the organization removes the server, the machine notices its beats being rejected and detaches itself, dropping the tunnel and every credential the cloud gave it.

The other verbs

isolation-server status                 # release, containers, pairing state
isolation-server update [--check]       # move to the channel's newer release (or say whether there is one)
isolation-server rename <name>          # what the Servers page calls this machine
isolation-server ssh --mode local|network|off [--bind host:port] [--advertise host:port]
isolation-server logs [-f] [<service>]  # server | doorman | opensandbox
isolation-server down [--purge]         # stop; --purge deletes the volume too
isolation-server disconnect             # unpair: detach and drop the tunnel

A server follows a channel — stable by default, beta for the next release a week early (isolation-server up --channel beta). A release is a manifest naming the three images by digest; update swaps them and keeps the volume.

State on disk

Everything the server owns lives in the isolation-server-data Docker volume: the configuration with the master token, the pairing and the tunnel credential; the view records; a 0700 directory for sandbox-lifetime secret state; the runtime's configuration and database. The isolation-server command keeps its own small state in ~/.isolation-server/compose (the role, the channel, the rendered compose file and the pins it applied). Workspaces live in Isolation Cloud as encrypted git bundles and a file tree in object storage, so wiping the volume or the whole disk loses nothing, which is the point of nothing lives in the sandbox.

One office server for the team

A Connected Server is the organization's, not the person's who paired it. Members launch their own sessions on it, each a separate sandbox on its own session/<id> branch, and a teammate's workspace is a 404 to everyone else. An Admin can list and stop sessions on the machine and read its log with /server-logs, but never open a session. One machine in the office, paired once, is the usual setup for a small team. Connected Servers are free forever; the organization only ever pays for a Cloud Server it asks for.