Isolade
Docs

Profiles

What a profile bundles — repos, build, runtime, network, and secrets — and how you edit it in the app.

A profile is the whole definition of an environment: the repos to bring in, the Dockerfile that builds the image, the per-instance runtime posture, and the profile’s identity — display name, git config, network policy, chat prompt, and appearance. Each profile lives in its own directory under ~/.config/isolade/profiles/, and the directory name is the profile id.

You create and edit profiles entirely in the app, under Settings → Profiles. Isolade owns the files inside the profile directory, so there’s nothing to hand-author. Secret values and harvested credentials are the only things kept out of the directory — everything else about a profile travels with it, so you can track ~/.config/isolade/ in git and a teammate or a second machine gets the same setup.

To make one, open Settings → Profiles and give it a name. Then fill it in using the tabs below. Guided setup, in the same place, does the first pass for you: it asks which repositories and toolchains you want, writes the Dockerfile, and runs the first build. What it produces is an ordinary profile, editable through exactly these tabs afterwards.

Repos and build

Edited on the Configuration tab.

A profile spans N repos, including zero — a Dockerfile-only environment where the agent starts from an empty /workspace and clones what it needs. Each repo is independent, with its own source (a GitHub URL or a local checkout) and an 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 repo’s name must be a valid Docker context-name component — lowercase alphanumeric with single ., -, or _ separators (for example app, web-app) — and unique within the profile. A few names are reserved because they’d collide with BuildKit’s own contexts and Isolade’s injected stages. Avoid naming a repo after a base image such as ubuntu, too, since a named context silently shadows FROM <name>.

The build points at a Dockerfile, resolved relative to the profile directory. Before shipping to BuildKit, Isolade renames your Dockerfile’s last stage and appends an agent-tooling stage on top of it, so you don’t install claude or codex yourself. The profile directory is the main build context, so files beside the Dockerfile are available to a plain COPY (for example COPY entrypoint.sh …); per-repo placement is left to you, copying from each repo’s named context with COPY --from=<name> ….

You can also list skill packages to install into the agent layer at build time (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.

Runtime

Edited on the Runtime tab. This is the per-instance posture applied when an instance VM boots; nothing here changes the built image.

  • Caches are host-side directories bind-mounted into the VM (under ~/.cache/isolade/caches/) at the same path inside the guest. Point a compiler cache here and it survives across instances.
  • Setup commands run once, the first time an instance VM is created. Start commands run on every VM boot — create and restart — for daemons, dev servers, and background workers. Each phase has a sync list (run in order, each must exit 0, the instance waits) and an async list (fired in parallel, only logged on failure).

Prompt

Edited on the Prompt tab. Every chat in the profile runs on a system prompt in two parts: a base prompt, and the profile’s own instructions below it. The instructions hold for the whole chat rather than riding along with one message, and where they conflict with the base prompt they win.

The base prompt is one of four — Optimized, Minimal, Unmodified, or Extended — each described on the tab where you pick it.

Both settings live in the profile’s config.toml, under [prompt].

Secrets

Edited on the Secrets tab. A profile declares the secrets exposed to its VMs, by name and allowed hosts; the values are entered separately in the UI. See Secrets.

Identity

These carry the profile’s identity rather than its build. They’re managed by the matching Settings tabs, and none of them is secret, so they travel with the profile in git.

  • Network (Network tab): the sandbox network policy applied to every instance VM. Internet access is either open (the default — all public destinations) or restricted to an allowlist (an essential built-in set plus the domains you add). You can also allow egress to the private/LAN range or to services on the host, and forward VM ports out to the host. Absent configuration means the default posture: open internet, no local/host access.
  • Git (Git tab): the committer identity (name and email) recorded on every commit an agent makes, and optional commit-signing through your SSH agent (for example Secretive). Isolade records only the public key line, the agent socket, and the on/off flag; the private key never enters the VM. The signing socket is machine-specific, so on another machine signing stays off until you point it at that machine’s agent.
  • Theme (Theme tab): per-profile UI theme and fonts, so the app re-skins when you switch profiles.
  • Models (Models tab): per-profile model-picker overrides — promote a model, tuck it behind the picker’s “More…” menu, or hide it, with a one-click reset. Only your changes are stored, so updates to the built-in catalog still come through.

How sources are fetched

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