# isx

> An AI agent in your terminal can read your API keys, tokens and SSH keys. isx gives each agent a full Linux workstation of its own instead, branched instantly from a template you prepared once. On it the agent has full autonomy, while your computer stays out of its reach; in it there are no credentials, because a transparent proxy on your host adds the accounts you assign it, such as its own GitHub identity, to its requests as they leave. Free and open source, light enough for a laptop, on Linux and macOS.

A branch is to a template what a git worktree is to a repository, except that the working copy is the whole machine, toolchain, dependencies and running services included; it is instant and starts ready to work. It is an Incus system container by default, or a KVM virtual machine (`--vm`) for the strongest isolation: a sandboxed workstation, not a sandboxed process on your own machine or an application container with a fixed set of tools. The agent's work comes back as commits through a git remote isx manages, so you review an immutable commit, never a directory the agent can still change. isx works with Claude Code, Codex CLI, Pi, GitHub Copilot CLI and other coding agents, and with everyday tools like `gh`, `git` and `curl`, unchanged. An agent on your host can drive isx over MCP (`isx mcp`): branch machines from templates you approved, run commands in them, and delegate whole tasks to the agents inside. Install with `curl -fsSL https://isx.run | sh`, Homebrew, DNF, APT or JBang.

If a person asked you to install isx and set it up, follow [Install with your agent](https://isx.run/docs/agent-install). You do the work, and the person holds the keys:

- Never run sudo or anything else as root. Install isx without root: `curl -fsSL https://isx.run | sh` on Linux, `brew install Sanne/tap/incus-spawn` on macOS. The Linux script installs into `~/.local/bin`, which a non-interactive shell may not have on its `PATH`: run `~/.local/bin/isx`, or add it.
- Read `isx init --plan --format=json` first. Each step says `who` must finish it: `none` is yours, `sudo`, `secret` and `approval` are the person's.
- Run `isx init --no-sudo --service --format=json`. Its progress goes to stderr and the JSON summary to stdout. Exit 0 means nothing is left for the person. Exit 75 means the steps that need root are in the script it names: hand the person `sudo sh <that script>` and stop, then run the same command again. Do not write a root script of your own from the plan's `sudo_script` fields: isx's script records what it ran, which the next run and the plan read.
- The root script adds the person to the `incus-admin` group, which your session gets only when the person starts you again from a new login: `id -nG` shows whether you have it. Until then, run each isx command as `sg incus-admin -c '~/.local/bin/isx …'`. `isx init` does this by itself, and other commands fail with "permission denied" on the Incus socket.
- Exit 76 means init finished but left steps for the person, which its JSON summary lists. Never ask for a secret: tell the person to run `isx account add <namespace>` (the one `isx init --plan` names) at their own terminal, and stop.
- Init asks for a credential only once a template needs one, so on a fresh host its `credentials` step reads `done`. After writing your template, run `isx init --plan --format=json` again: its `credentials` step then names each missing credential and the `isx account add` command for it.
- Never write `~/.config/incus-spawn/mcp.yaml` or choose which templates agents may use: ask the person to run `isx mcp setup`, and stop.
- Write a template without an editor with `isx templates new <name> --from -` (YAML on stdin), then `isx build <name>` and `isx branch <instance> --from <name> --format=json`, which opens no shell. A first build takes a few minutes: let it finish in the foreground before you end your turn, since ending your turn can stop it. It warns at its start when the template needs a credential that is missing; it still builds, and `isx branch` refuses until the person adds it. The person's first template has you in it: the same coding agent. Find your isx tool by what you know you are, and use its name as `<tool>` below:

  | You are | `<tool>` |
  |---|---|
  | Claude Code | `claude` |
  | Codex CLI | `codex` |
  | Pi | `pi` |
  | Gemini CLI | `gemini-cli` |
  | Bob Shell | `bob` |
  | GitHub Copilot CLI | `copilot` |

  ```yaml
  name: tpl-agent
  description: <your name> on the base OS
  parent: tpl-minimal
  tools:
    - <tool>
  default-action: <tool>
  ```

  Keep `tpl-minimal` as its parent. `tpl-dev` is deprecated, and its `gh` needs a GitHub credential before any branch. For `copilot`, write `shell-command: copilot` instead of `default-action`. If you cannot tell which agent you are, or you are not in the table, ask the person which agent to put in the template, and stop. Environment variables are only a hint, since an agent started from another agent's shell inherits that agent's: `CLAUDECODE`, `CODEX_THREAD_ID`, `PI_CODING_AGENT`, `GEMINI_CLI`.
- Register isx's MCP server with yourself: `<isx> mcp register claude` for Claude Code, `<isx> mcp register codex` for Codex CLI. Any other agent puts the entry `<isx> mcp config` prints into its user-wide MCP settings, unchanged. On Linux both run the server through `sg incus-admin` when the host has `sg`: a session from before the root script lacks that group, and the Incus socket refuses it with "permission denied". On a host without `sg`, the server reaches Incus only once the person starts you again from a new login, and `isx mcp register` says so. `<isx>` is the full path of isx: `~/.local/bin/isx` from the install script, else what `command -v isx` prints. If your isx says `register` is not a command, it is a release from before it: register `<isx> mcp` with yourself, and on Linux, when `command -v sg` finds it, `sg` with the arguments `incus-admin`, `-c` and `<isx> mcp` instead.

  Your client may load it only in a new session; then do not write a client of your own to test it, but tell the person it is ready once they start you again. To check it, call `list_templates`: it lists the templates the person approved, and none before `isx mcp setup`. `list_instances` lists only instances created over MCP, so the first instance, made with `isx branch`, is not in it. `isx mcp setup` offers every template that installs a coding agent. You can `create_instance` from any template the person approved and `exec` in it, but `delegate` runs only `claude`, `codex` and `pi`.
- On Linux, when you are done, tell the person in these words: "If isx's tools are refused over MCP, with permission denied on the Incus socket, restart me from a new login, or log out and in again." That gives you the `incus-admin` group the root script added. On macOS there is no such group, so do not say it.

## Docs

- [Install with your agent](https://isx.run/docs/agent-install): the prompt that has a coding agent install and set up isx, and the three steps that stay with the person
- [Full documentation](https://isx.run/llms-full.txt): every page below as one Markdown file
- [Quick start](https://isx.run/docs#quick-start): install, one-time host setup, a first template and a first agent
- [Credential isolation](https://isx.run/docs#credential-isolation): how agents use their accounts with no credentials in their workstation
- [Branching](https://isx.run/docs#branching): creating workstations from templates, network modes, and fetching an agent's commits
- [Installation](https://isx.run/docs#installation): platforms, updating and uninstalling
- [Templates](https://isx.run/docs/templates): defining, building and rebuilding templates
- [Agents](https://isx.run/docs/agents): Claude Code, Codex CLI, Pi, Gemini CLI, Bob Shell and GitHub Copilot CLI, agent skills and environment notes
- [Tools](https://isx.run/docs/tools): built-in tools, and adding your own with YAML definitions
- [Configuration](https://isx.run/docs/configuration): files, credential accounts (several per service, chosen per instance), exposed host ports for a service on your host such as Ollama, and caching
- [Delegating from an agent on your host (MCP)](https://isx.run/docs/mcp): `isx mcp`, approved templates, Claude Code, Codex and Pi workers, delegated tasks, a coordinator in an instance
- [Driving `isx mcp` from a program](https://isx.run/docs/mcp-protocol): structured results, task states, notifications, idempotency keys, activity counters
- [Driving isx from other tools](https://isx.run/docs/integrations): orchestrators such as Orca and herdr, with an instance per task, and host routes to a controller of your own
- [CLI reference](https://isx.run/docs/cli): every command, and the stable output formats for scripts
- [Compared with other sandboxes](https://isx.run/docs/sandboxes): a sandboxed process, workload or workstation, and where isx and the other agent sandboxes sit
- [FAQ](https://isx.run/docs/faq): URL clicks in Codex, the clipboard, a model server on your host such as Ollama, and why there is no read-write project mount

## Optional

- [Why full system containers?](https://isx.run/docs/sandboxes#why-full-system-containers)
- [Source code on GitHub](https://github.com/Sanne/incus-spawn)
- [Issues](https://github.com/Sanne/incus-spawn/issues)