Workspaces

The config.toml reference for repos, build, ports, caches, and secrets.

A workspace lives in its own directory under ~/.config/isolade/workspaces/. The directory name is the workspace id, and config.toml inside it holds the definition: one or more source repos, the Dockerfile to build, optional forwarded ports, and host-side caches to bind in.

A workspace spans N repos. Each [[repos]] entry is independent, with its own source and optional branch. Every repo reaches your Dockerfile as a BuildKit named context, keyed by its name, holding the working tree and its .git. Your Dockerfile copies from that context and decides where the files land. The usual choice is /workspace/<name>, the directory agents work in.

A single local repo

ports = [5173]

[build]
dockerfile = "./Dockerfile"

[[repos]]
name   = "app"                     # exposed to the Dockerfile as context "app"
source = "~/src/app"

Multiple repos

Three repos pulled from GitHub, one on a topic branch, with a shared ccache:

[build]
dockerfile = "./Dockerfile"

[[repos]]
name   = "app"
source = "https://github.com/example/app"
branch = "feature/new-api"

[[repos]]
name   = "docs"
source = "https://github.com/example/docs"

[[repos]]
name   = "web-app"
source = "https://github.com/example/web-app"

caches = ["~/.cache/ccache"]

Field reference

[[repos]] (one or more, required)

• name: the repo’s identity. It names the BuildKit context <name> your Dockerfile copies from, and it’s the dedup key. Must be a valid Docker context-name component: lowercase alphanumeric with single ., -, or _ separators (for example app, web-app). Unique within the workspace. A few names are reserved (they’d collide with BuildKit’s own contexts and the injected stages): context, dockerfile, gc_user_base, gc_layered. Avoid naming a repo after a base image such as ubuntu, too, since a named context silently shadows FROM <name>.
• source: one of https://github.com/owner/repo[.git], github.com/owner/repo, file:///abs/path, or an absolute or workspace-relative local path. Local paths must point at an existing Git checkout.
• branch (optional): git sources only. Defaults to the remote’s default branch.

[build] (required)

• dockerfile: path to the Dockerfile, resolved relative to the workspace directory (typically "./Dockerfile", next to config.toml). Before shipping to BuildKit, Isolade renames your Dockerfile’s last stage and appends an agent-tooling stage on top of it. The workspace directory is the main build context, so files beside config.toml are available to a plain COPY (for example COPY entrypoint.sh …). Per-repo placement is left to you: copy from each repo’s named context with COPY --from=<name> ….

ports (optional)

TCP ports forwarded from each instance VM out to the host when the instance is created. A dev server on 5173 inside the VM becomes reachable on the host.

host_ports (optional)

Host bridge TCP ports the VM is allowed to reach (egress). Each becomes an allow rule for host.microsandbox.internal:<port>. By default the VM can reach no host port. This is the opposite direction of ports, which forwards guest ports out.

caches (optional)

Host-side bind mounts under ~/.cache/isolade/workspaces/<name>/caches/. Paths must start with ~/ or $HOME/, and they mount at the same location inside the VM. Point a compiler cache here and it survives across instances.

prelude (optional)

Text prepended (wrapped in <prelude>…</prelude>) to the first user message of every new chat in this workspace. The database keeps the user’s original message, so the prelude stays invisible in the UI and only reaches the model.

skills (optional)

Skill packages installed into the agent layer via npx skills add, for both Claude and Codex (for example ["example/skills"]). Each entry is passed verbatim to the skills CLI and supports its shorthands.

[[secrets]] (optional)

Declares the secrets exposed to the workspace’s VMs, by name and allowed hosts. Values are entered separately in the UI. See Secrets.

How sources are fetched

Repos backed by GitHub or file:// URLs are kept as managed shallow checkouts under ~/.cache/isolade/workspace-checkouts/. Rebuilding a workspace clones or updates each managed checkout before bundling. Creating an instance uses the cached checkouts as-is and does not fetch.