Architecture

Packages, the builder VM, agent-login internals, and the data layout.

The implementation reference. For installation and day-to-day use, start with the Overview.

Monorepo packages

By default the server runs the sandbox in-process: a single sidecar, no separate listener, driving the VM manager, builder, and registry through direct calls behind a SandboxApi interface. Setting ISOLADE_SANDBOX_URL flips the server to talk to a standalone sandbox over HTTP instead, which is the external-sandbox dev mode.

The API server binds 127.0.0.1 on an OS-assigned port that the Tauri host injects into the webview as window.__ISOLADE__. CORS is locked to the app and dev origins.

The sandbox drives VMs through microsandbox (Apple Silicon macOS, or Linux with KVM). microsandbox is an optional dependency: if it isn’t installed, point ISOLADE_SANDBOX_URL at an external sandbox service.

Builder VM (BuildKit-in-VM)

Workspace builds run in a single shared microVM hosting buildkitd, lazy-booted from docker.io/moby/buildkit on the first build request and kept warm for the lifetime of the sandbox process. The host never runs docker build.

The BuildKit layer cache (the FROM image content store, RUN-step outputs, and --mount=type=cache directories) survives across builds and across workspaces. Restart the sandbox process to drop it.

The builder pushes to the local registry over the host bridge IP (auto-detected, or SANDBOX_HOST if set), because localhost doesn’t resolve from inside the VM. Pushed refs use that bridge IP, and the host reaches them through the same address.

Agent account internals

Isolade signs in to Claude and Codex through a throwaway VM running the CLI’s loopback OAuth flow. See Agent accounts for the user-facing flow. Two mechanisms make it work.

Login callback bridge

The browser callback reaches the in-VM login server through a small bridge. Isolade publishes the CLI’s loopback port via microsandbox and runs a host-side TCP proxy on the redirect port, plus a guest-side proxy for Claude, whose loopback port is random. On success the credential is harvested into the store at ~/.local/share/isolade/auth/{claude,codex}/ (XDG data, 0600, never git-tracked).

Credential propagation

That auth directory is bind-mounted into every instance VM, and a tiny watcher keeps each VM’s credential file in sync with it by access-token expiry, newer wins. A token refresh the CLI performs inside one VM propagates back to the store and into every other live VM, so there’s no central refresher to run. The refresh token never leaves the store or the VMs.

Data layout

HTTP API

For the endpoint reference, see HTTP API.