How it works

The path from a config file to a running agent, step by step.

Isolade turns a directory in git into a fleet of disposable agent sandboxes. Here’s the whole path.

1. A workspace describes the environment

You write a config.toml and a Dockerfile in a directory under ~/.config/isolade/workspaces/. The TOML names the repos, the ports to forward, the caches to mount, and the secrets to expose. None of it holds a secret value. See Workspaces.

2. The build runs in a VM

Image builds run inside a single shared microVM that hosts buildkitd. The host never invokes docker build. Your repos arrive as named build contexts (each under its name), Isolade stacks an agent-tooling stage on top of your last stage, and the result is pushed to a local OCI registry.

The layer cache survives across builds and across workspaces. The first build of a workspace is the slow one. Later builds reuse cached layers, the model FROM image, and any --mount=type=cache directories. See Architecture → Builder VM.

3. An instance is a fresh microVM

Creating an instance boots a new microVM from the workspace’s image. Spin up as many as you want. Each one is independent: its own filesystem, its own network policy, its own diff.

The agent’s OAuth credential is mounted in, declared secrets are registered as placeholders, and forwarded ports are wired to the host. Then the agent tooling is ready.

4. Secrets never enter the VM

Declared secrets are registered as placeholders, so the VM only ever sees a worthless stand-in. When it makes an outgoing TLS request to one of the hosts the workspace named, the egress proxy substitutes the real value in; a request carrying the placeholder to any other host is dropped. The real secret only ever reaches a host you allowlisted, and never lands in the VM, the database, or a log.

That’s part of what makes “run unattended” safe. An agent inside the VM can read, write, and execute freely, but it can’t read the secrets it uses — and the blast radius is a disposable VM you throw away when you’re done. See Secrets.

5. You watch, steer, and review

Agents run in the desktop app. You see every instance, its live diff count, and its chat. Switch between agents, interrupt one that drifts, open a terminal into any VM, and review the diff before any of it lands in your tree.

When the work is done, throw the instance away. The image stays cached, so the next one boots fast.