CLI reference

Every isx command, with what --help does not say. isx <command> --help lists all of a command's options. Scripting isx covers the plain and json output formats, the fields each query command prints and the exit codes.

isx

Launch the interactive TUI. When the TUI cannot open, as when stdout is not a terminal, it prints the instance table instead.

isx

isx init

Set up the host once: install Incus, configure credentials and their accounts, and test connectivity. Running it again is safe, and is how you add, rename or remove an account. On a fresh Linux host it adds you to the incus-admin group, which other terminals get at your next login or with newgrp incus-admin.

isx init [--no-sudo] [--search-path=<dir>,...] [--code-dir=<dir>,...] [--fork-templates] [--service | --no-service] [--format=table|plain|json]
isx init --plan [--format=table|plain|json]

Without a terminal

isx init can run with no terminal, as an agent runs it. Each question that is not a secret has a flag that answers it, with or without a terminal:

There is no flag, variable or piped input for a secret. Adding a missing credential stays your step, which you do with the isx account add command. Approving templates for agents stays your step too, which you do with isx mcp setup. A question no flag answers is skipped when there is no terminal, and the step says how to answer it later.

With --format=json or plain, init ends with a summary on stdout and its progress on stderr. The summary has a record per step, with the fields isx init --plan prints, their values read after the run. A field skipped says that init skipped the step's question because there was no terminal.

The last field, declined, says the answer was no, given by you or by a flag such as --no-service.

The run then exits 76 when it finished but left a step only you can do, such as a credential, an approval or a step that needs root. A run that waits on the root script, exit 75, prints the summary too; a run that fails exits 1 and does not print the summary.

isx init --plan says what isx init would change on this host, and does not change the host. It does not ask a question, write a file or run sudo, and it asks Incus only to read. On macOS it does not start the VM, so what Incus holds stays unknown while the VM is stopped.

On Linux, isx init itself starts with sudo -v, so running it needs sudo even when every step is done.

Some of what init checks only root can read, such as the btrfs sudoers rule. Firewall rules are read without sudo where the host's polkit policy allows it or polkit is not installed, and never in a way that asks for a password.

The plan reports anything it could not read as unknown, saying what it skipped and why. Its check_commands are the sudo commands that let you check what the plan skipped.

The plan lists every step init would take, in its order, with what it is for and its state:

Each step also says who must do what is left of it:

With --format=json each step is an object with these fields, in order:

plain prints the same fields, one step per line, as the formats below describe. The last field, sudo_script, holds the step's lines of the script isx init --no-sudo writes.

Without sudo

isx init --no-sudo does not run any step as root, for you or for an agent driving the install. It writes every step that needs root into one script, ~/.local/state/incus-spawn/init-privileged.sh, with a comment saying why each is there. It then exits 75 and names the script.

Read the script, run it as root with sudo sh, then run isx init --no-sudo again. The second run checks that each step took effect, then does the rest of the setup as you. A fresh host needs the script once, unless the second run moves the bridge off a VPN's subnet.

Some of what the script does only root can check afterwards, such as the btrfs sudoers rule. The script records what it ran in /var/lib/isx/init-applied, which the second run reads for those steps. isx init --plan reads that file too, so the plan reports that work as done.

Once nothing needs root any more, the second run removes the script. When the second run itself finds root work, such as a redirect to move after it moved the bridge off a VPN's subnet, it writes a new script and exits 75 again.

On a host with apt, the script refreshes the package lists once, before its first install, as isx init with sudo does. A step isx cannot write as a script, such as installing packages on a host without a package manager it knows, stops the run and names what to do yourself.

On a UFW host the script edits /etc/ufw/before.rules itself, keeps a copy, and puts the copy back if UFW refuses the new file. If the blocks isx marks in that file are broken, the script stops and leaves the file as it was. On macOS isx init needs no administrator, so --no-sudo has no effect there.

isx build

Build or rebuild a template image. While another isx builds or updates the same template, the build is refused.

isx build [<template>...] [options]

Every build keeps the commands its definitions ran in ~/.local/state/incus-spawn/build-logs/<template>.log, with all that each printed and its exit status. These are each tool's run, run_as_user and verify commands and each repository's prime. The log is written as each command ends, so tail -f follows a build, and a failure report names it.

A template's name may be at most 52 characters, since isx builds it as <name>-rebuilding first and swaps it in once built. isx refuses a longer name before it builds anything, the template's parents included.

Several templates build in one invocation:

• With plain names, each builds in turn, a named parent before its child. Each gets any parent that is missing or out of sync, so a parent they share builds once.
• With --with-parents or --with-descendants, they build as one batch with one confirmation, parents before children and every template once.
• With an unknown name anywhere in the list, isx does not build any of them.

A target that fails does not stop the others: isx skips what inherits from it and builds the rest. The build then exits 1 with one Some templates failed to build: line on stderr naming every template it left unbuilt, including a parent that failed to build for a target.

isx branch

Create a new instance as a copy-on-write clone of a template or of an existing instance.

isx branch <name> [options]

isx shell

Open a shell in an existing instance.

isx shell <instance>
isx shell <instance> --session <name>
isx shell <instance> --no-attach
isx shell <instance> --task [<task-id>]

When the instance auto-attaches to zmx or tmux, every isx shell enters its session isx, so two terminals show the same screen. --session <name> enters another session instead, and creates it when it is missing. A name is 1 to 32 letters, digits, - or _, and does not start with -. --no-attach opens a plain login shell outside any session.

With --task, it opens the conversation of a task an agent delegated over MCP instead of a shell. The agent resumes the conversation in the directory it worked in, and leaving the conversation ends the session.

Without an id it joins the only task in the instance. With several tasks, it lists them, each with the command that joins that task, and exits.

isx refuses a task in the middle of a turn until the turn ends. Plain isx shell into an instance isx mcp made prints the --task command before the prompt.

Copying from an agent inside the instance needs an OSC 52-capable host terminal. See the FAQ.

With the shell-status-bar feature enabled, isx pins a two-line status bar at the bottom of the terminal. It shows the instance name and template, then its IP address, its network mode unless that is full, and the names of its repositories. Press F12 to open a quick-action menu with shortcuts from tool actions that set shell_menu: true. Enable it with:

# ~/.config/incus-spawn/config.yaml
features:
  - shell-status-bar

isx start

Start an instance and make it ready for use, without opening a shell.

isx start <instance>

isx prepares the instance as isx shell would, so the instance receives its credential proofs. An instance already running is checked and left running. If another isx process is starting or stopping it, isx start waits for that first, for up to two minutes.

isx stop

Stop a running instance.

isx stop <instance>

Stopping an instance that is already stopped succeeds, so a script can repeat it. A frozen instance cannot shut down, so isx stop refuses it with an error. If another isx process is starting or stopping it, isx stop waits for that first, for up to two minutes.

isx run

Run the default action or a specific action on an instance.

isx run <instance> [options]

It exits 1 when no action matches or the action fails.

isx destroy

Destroy an instance, or every built template or every instance at once.

isx destroy <instance>
isx destroy --all-templates      # destroy all built templates (derived first)
isx destroy --all-instances      # destroy all instances

Destroying an instance an external tool owns without --owner asks first. Without a terminal, a script must pass --skip-confirmation.

isx list

List the instances isx created, without opening the TUI.

isx list [options]

It does not list templates: isx templates lists those. On macOS it starts the VM if the VM is stopped, except with -q, which shell completion runs. See Scripting isx for the plain and json formats and the fields.

isx update-base

Check for base image updates and install them.

isx update-base [<release-tag>] [options]

Pass a release tag, such as fedora-45-20261111, to pin to that version. The pin is written to ~/.config/incus-spawn/base-image-pin.yaml and changes only the base image tpl-minimal downloads. For a tag of another Fedora release, such as fedora-44-... on an isx that ships Fedora 45, the pin uses that release's own image name and file names.

--latest follows the newest release of the built-in's line, never another Fedora or a channel.

isx update-all

Update system packages, npm globals and git-fetched repos in all templates. It does not re-clone repos or reinstall tools: use isx build for that. Each template is updated in a copy that replaces it only once every step succeeded. If a step fails, the command exits non-zero and that template stays as it was.

isx update-all [options]

isx templates

Manage template definitions. Bare isx templates runs list.

isx templates <subcommand>

isx templates list

List the available templates, each with its description.

isx templates list [options]

isx templates new

Create a new template definition. The name is used exactly as given, and the file is named after it: isx templates new my-app writes my-app.yaml. isx refuses a name whose file is the one an override of a built-in template uses, such as dev. Without a name, it writes new-template.yaml for you to name in the editor.

isx templates new [<name>]
isx templates new <name> --from <file>

With --from, it takes the whole definition from a file, or from stdin for -, and does not open an editor. It checks the definition as the editor does, then stores the definition only when it has no error. The definition's name: must be the name you give. It never prompts, so a script or an agent can run it.

With an invalid definition, isx does not write a file and exits 1. The check also lists what the template reaches beyond its instance, so you can review a template an agent wrote before you build it.

isx templates validate

Check a template definition without storing or building it. It takes a file, - for stdin, or the name of a template you have. It runs the same check as isx templates new --from and exits 1 when the definition has an error.

A credential the template's tools need that is not configured is a warning on tools, naming the command that configures it.

isx templates validate <file-or-name>

isx templates edit

Edit a template definition in $EDITOR. It takes the template's exact name, as isx build and isx branch do. Editing a built-in template creates a user-level override of it.

isx templates edit <name>

isx tools

List and inspect the available tool definitions. Bare isx tools runs list.

isx tools <subcommand>

isx tools list

List the available tools.

isx tools list [options]

isx tools show

Show the details of one tool definition.

isx tools show <name>

isx account

Add credentials, and show or change which credential account an instance uses. Bare isx account runs list.

isx account <subcommand>

isx account add runs that one step and nothing else: no sudo, no other step. Name the credential by namespace (github, claude, openai) or by tool (gh, codex); without a name, choose from init's credential menu.

Adding a second account goes through the same account menu. The proxy applies the change automatically.

isx project

Manage project templates defined by an incus-spawn.yaml file.

isx project <subcommand>

isx project create

Create a project template from a parent base image.

isx project create <name> [options]

A project name may be at most 52 characters, since isx builds it as <name>-rebuilding first. Re-creating an existing template builds the new one alongside it and replaces it only once the build succeeds. If a repository fails to clone or the pre-build fails, the command exits non-zero, deletes the incomplete build and keeps the previous template.

isx project update

Update an existing project template: its packages, repos and dependencies.

isx project update <name> [options]

The update runs in a copy that replaces the template only once every step succeeded. If any step fails (system update, npm update, git fetch, pre-build), the command exits non-zero and keeps the template as it was.

isx proxy

Manage the MITM authentication proxy.

isx proxy <subcommand>

isx proxy start

Start the proxy.

isx proxy start [options]

On Linux, --gateway-ip must be the bridge's own address, which is where every isx command looks for the proxy.

When the bridge can be read, the value must be exactly the bridge's gateway address. When the bridge cannot be read, the value must be a private (RFC 1918) or loopback address that matches the gateway isx init recorded, if init recorded one.

On macOS, the value must be the host's VM-facing bridge address.

isx proxy dump

Run a pass-through proxy for host-side traffic capture.

isx proxy dump [options]

isx doctor

Diagnose host, proxy, VM and tunnel health, and offer to fix the problems found.

isx doctor [options]

Each finding carries a mark:

A fix in a base image reaches only instances built after it. So doctor notes the templates on an older base image than a rebuild would use, and the instances branched from them. That is a note, not an issue to address, unless the older release lacks a known fix a rebuild would bring, such as the network watchdog one.

--bundle creates an archive to attach to a GitHub issue. isx redacts credentials before it writes anything, and REDACTIONS.txt in the archive lists what it removed.

--explain sends the findings and the archive's redacted files to the account isx ask uses, which is billed for it. The answer lists the likely causes, the command to run next and the repository a fix belongs in. isx prints the size of what it sends before sending, and asks first when the size is over 100 KB.

The answer is a suggestion, so check it before acting on it.

isx clean

Remove cached data, state or configuration.

isx clean <subcommand> [options]

All subcommands accept these options:

On macOS, isx clean state keeps the VM's data disk, with every instance, template and image, unless you pass --delete-instances. It refuses to run while the VM runs: stop the VM first with isx vm stop. Run isx init afterwards: the VM needs the appliance again before it boots on the kept disk.

isx clean pool --base-images also removes the downloaded base images, which the next build downloads again.

isx clean all does not delete any Incus template or instance unless you pass --delete-instances, which on macOS also deletes the VM's data disk. Like isx clean state, it refuses to run while the VM runs.

isx reset

Return isx to a freshly installed state. It removes all instances and templates, cached images and downloads, the proxy service, the VM on macOS, and all configuration, including SSH keys and the CA certificate. It shows what it will remove and asks first. Run isx init afterwards to set up again.

isx reset

isx vm

Manage the VM that runs Incus on macOS; the command exists only there.

isx vm <subcommand>

When the VM stops answering

When isx cannot reach the VM, run isx doctor first. It starts a stopped VM, and clears leaked connections in the VM's forwarder without a reboot, so running containers keep running. It offers to restart the VM only when neither a stopped VM nor leaked connections are the cause.

A restart, by doctor or with isx vm restart, keeps your instances and templates. It stops running containers, and applies any pending appliance update. If the VM still does not answer, isx vm console follows its serial console, and isx doctor --bundle collects a support archive to attach to an issue.

Last resort: isx vm reset deletes every instance, template and cached image in the VM, with any work stored only inside them. It asks first. Rebuild your templates afterwards with isx build --all.

isx vm stop

Ask the guest to shut down, and wait up to 30 s for it. The guest stops Incus and its instances and syncs the disks.

isx warns when the guest did not shut down and had to be stopped with signals, which loses the writes of the last few minutes. That happens at every stop of an appliance from before the fix for #881, until isx vm restart applies a newer appliance.

With --require-clean, such a stop also exits 4, and a VM isx could not stop exits 1.

isx vm restart

Stop and restart the VM, applying any pending appliance updates. It keeps instances and templates, but stops running containers. When the VM is not running, it says so and does not start the VM: use isx vm start for that.

isx vm restart [options]

isx vm resize

Grow the VM data disk that backs the storage pool.

isx vm resize <size>

The size, such as 100G, must be larger than the current disk: the disk only grows.

isx vm reset

Wipe the VM's storage pool, for when the pool cannot be repaired, as with orphaned subvolumes reported by isx doctor.

isx vm reset [options]

It deletes every instance, template and cached image. isx starts a stopped VM to list them and asks before it deletes them, and without a terminal it needs --yes. Rebuild your templates afterwards with isx build --all.

isx ask

Ask the AI any question about isx; it uses AI tokens. It needs an Anthropic API key, Vertex AI or an OpenAI key, since a Claude subscription token only serves Claude Code. Claude Max and Team plans include monthly API credits that pay for such a key. isx init offers to add such a key beside a subscription account.

isx ask <question...>

An answer is AI-generated and can be wrong, so isx asks the AI to end the answer with the documentation sections the answer relies on: check the answer against them. A note on stderr says so after every answer, and stdout holds only the answer.

isx mcp

Serve isx to an agent on this host over the Model Context Protocol, on stdio. The agent starts it, not you, once isx mcp register registered it:

isx mcp register claude

See Delegating from an agent on your host for what it offers and how to approve templates.

isx mcp --caller-instance <name> serves an instance branched with --mcp-client instead. The proxy runs this command for each connection that instance makes to https://mcp.isx.internal/mcp, as a coordinator in an instance.

isx mcp setup

Run the "Agent Access over MCP" step of isx init alone: approve the templates agents may use, and register isx mcp with Claude Code when it is installed. It asks the same questions and writes the same mcp.yaml.

isx mcp setup

It needs a terminal, and takes no option naming a template. Without a terminal it does not change mcp.yaml and exits 1, since approving templates is a step for you, not for an agent.

isx mcp register

Register isx mcp with Claude Code, Codex or opencode, through that agent's own mcp add command.

isx mcp register claude
isx mcp register codex
isx mcp register opencode

It replaces an existing isx entry, and exits 1 when the agent is not installed or its command fails.

On Linux the entry runs the server through sg incus-admin when the host has sg and you are in that group. An agent started before you joined the group then still reaches Incus. Without sg the entry is plain, and the agent reaches Incus once you start it again from a new login.

isx mcp config

Print the entry that starts isx mcp, as the mcpServers JSON most MCP clients take in their settings.

isx mcp config

It names the installed isx by its full path and does not change any file. On Linux its command is sg with incus-admin, as isx mcp register writes it, when the host has sg and you are in that group. Paste it into the settings of an agent other than Claude Code, Codex and opencode, such as Cursor or Gemini CLI.

isx completion

Print a shell completion script.

isx completion [<shell>]

Supported shells: bash (the default), zsh, fish and pwsh.

Every script asks isx itself on every TAB, so it offers only the commands this platform has. It completes instance names, templates, tools, accounts and option values such as --format. Add isx completion pwsh | Out-String | Invoke-Expression to your $PROFILE to load the PowerShell one.

The scripts also complete <namespace>=<account> for isx branch --account and isx account set, and the namespaces for isx account unset. For isx account add they offer each credential by namespace and by tool, such as github and gh. They offer names only, never credentials. The zsh, fish and PowerShell scripts mark each namespace's default account; bash does not show descriptions.

Scripting isx

Query commands print plain and json output that a script can rely on, and exit codes that say what happened.

Query commands take --format=table|plain|json: isx init --plan, isx list, isx templates [list], isx templates validate, isx tools list, isx tools show, isx account list, isx account show, isx proxy status, isx proxy activity, isx doctor, isx vm status (macOS), isx update-base --list and isx branch.

Formats

• table is for people. It may change in any release, so do not parse it.
• plain prints one record per line, its fields tab-separated, with - for an empty field. There is no header, padding, colour or glyph, and no results means no output.
• json prints an array of objects, or one object for a command about one thing (tools show, proxy status, vm status, branch).
• Both plain and json are stable. Fields may be added at the end, but are never renamed, removed or reordered.

Values

• A list value is an array in json, and its elements joined by , in plain.
• An absent value is null in json and - in plain.
• Sizes are in bytes.
• Times are ISO-8601 with their offset: 2026-10-05T12:34:56+02:00, or 2026-10-05T12:34:56Z on a host whose zone is UTC, so match both forms.
• An instance stamped by an older isx release may carry only a date, which prints as an ISO-8601 date (2026-09-01). A time isx cannot read is null.

Control characters

Neither format lets a value write a control character to your terminal. A value can hold one: an instance stamp set by hand with incus config set can carry an escape sequence.

• plain keeps each record on one line and safe to print, so every control character in a value becomes a space. The original characters are then lost.
• json keeps every value unchanged, writing each control character as a JSON escape that any JSON parser turns back into the original. Read json when you need a value exactly.

The characters plain replaces and json escapes:

• the C0 controls U+0000 to U+001F, tab, line feed, carriage return, backspace, form feed and ESC among them;
• DEL;
• the 8-bit controls U+0080 to U+009F;
• U+2028 and U+2029;
• the bidirectional embeddings, overrides and isolates U+202A to U+202E and U+2066 to U+2069, which would make your terminal show the rest of the line out of order.

json writes \t, \n, \r, \b and \f for tab, line feed, carriage return, backspace and form feed, and \uXXXX for every other one.

Output streams

• Results go to stdout. Errors and diagnostics go to stderr, so stdout holds only results.
• Commands that act (build, branch, destroy, ...) report their steps on stdout and their warnings and notes on stderr.
• A status command's report is its result in every state: isx proxy status prints it on stdout whether or not the proxy is healthy, and the exit code says which.
• When isx cannot read what Incus answered, the command fails with exit 1 and the reason on stderr. It never prints an empty result.

isx writes colour, clickable links and animated progress only when stdout is a terminal. When stdout is redirected or piped, or NO_COLOR is set to a non-empty value, neither stdout nor stderr holds escape sequences.

isx cannot tell whether stderr alone is a terminal, so isx build tpl-minimal 2>build.log run from a terminal still colours the warnings in build.log. For a clean log, redirect both streams or set NO_COLOR=1.

Fields of isx list

isx list prints name, status (running, stopped, ...), ipv4, parent, runtime (container or virtual-machine), created, mcp_state, mcp_purpose, base_image, owner, owner_id and mcp_client, in that order. mcp_state and mcp_purpose are null (-) unless an isx mcp session made the instance. mcp_purpose is then what the agent said the instance is for, or null, and mcp_state is one of:

base_image is the base image release the instance was built from, such as fedora-44-20261001. It is null when Incus recorded none, as for an instance built from an image of your own. A fix in a base image reaches only instances built after it, and isx doctor names the ones a rebuild would move to a newer release.

owner and owner_id are the external tool that controls the instance and its handle for it, as isx branch --owner and --owner-id stamped them, or null. The table shows the owner in its OWNER column, beside how an isx mcp session holds its instances.

mcp_client is true for a coordinator, an instance that may drive isx over MCP. What it may control depends on its template's definition, which isx list does not read; the TUI's instance details show it.

For names alone, use isx list -q:

for name in $(isx list -q --status=stopped); do isx destroy "$name" --skip-confirmation; done
isx list --format=json | jq -r '.[] | select(.parent == "tpl-java") | .name'

Fields of the other commands

The fields of each command, in order:

The sections below explain the fields that need an explanation.

isx templates fields

parent_rebuilt is never set for a VM whose parent is a container, or the reverse, because isx builds such a template from the definitions and does not copy the parent. version_outdated, definition_changed and parent_rebuilt are null for a template that is not built. Everything from built on is null when Incus could not be asked, with the reason on stderr.

isx build --out-of-sync builds the templates that are not built, rebuilds those with version_outdated, definition_changed or parent_rebuilt, and rebuilds the descendants of every template it builds.

Template check fields

isx templates validate and isx templates new --from print one object in json.

A finding's field is the key at fault, such as parent, repos[1].depth or coordinator.control-over. It is null when the file does not parse at all. A reach entry's kind is host-image (a file:// base image), host-resource, host-source, gui, account or coordinator. Only the definition's own fields count, not its parent's.

plain prints one line per finding, <severity> <field> <message>, then one per reach, reach <field> <detail>, tab-separated.

isx account list fields

pinned_by and following are null when Incus could not be asked, with the reason on stderr. plain prints that as -, like an empty list, so read json to tell them apart.

isx account show fields

On that next start or shell, isx also fills in an identity missing from an instance whose template an older isx built, but identity_pending does not list that identity.

isx proxy status fields

The record is printed in every state, and the exit code follows the exit codes table. So unknown exits 1 like not_running: read status to tell them apart.

isx proxy activity fields

One record per instance the proxy knows, by name, then one whose instance is null: traffic from no known instance, which is the host or an address the proxy has not listed.

The last five fields describe the proxy, not one instance: they are set on the unattributed record alone, and are null on the others. The table ends with the refused proofs and a failed listing when there are any, and the unplaced instances when there are address misses.

With --by-domain, one record per instance and domain: instance, domain, counting_since, requests, in_flight, last_activity_at, request_bytes, response_bytes. domain is an intercepted domain, a subdomain counted under it, or (other).

It exits 1 when the proxy cannot be read.

isx doctor fields

level is ok, note, warn or fail. detail and remediation are free text for people: key a script on level and label. In a script format, isx does not offer or apply any fix, and --bundle cannot be combined with it.

isx vm status fields

It exits 1 when Incus is unreachable.

isx update-base --list fields

The current base image is unlisted when it is older than every release fetched, unpublished or deleted. It then gets a record of its own, last, with no date. The listed field alone does not tell you the image's age.

isx branch fields

isx branch <name> --format=plain prints name alone. Progress goes to stderr and no shell is opened, so name=$(isx branch my-box --from tpl-java --format=plain) captures the name. plain never gains a field, so that this capture keeps working.

--format=json adds the fields a program needs to reach the instance:

The SSH fields are null when the template does not install sshd, or when isx cannot create its SSH key. isx creates the key before printing its path, and authorizes the key in the instance when the instance starts, so a --no-start branch is reachable once started.

A plain ssh <name> uses the instance's own Host block, which never starts a stopped instance.

Exit codes

Exit 1 covers a value the command rejects (--format=yaml, --status=frozen), Incus unreachable, and the like. isx doctor also exits 1 when a check fails, isx vm status when Incus is unreachable, and isx proxy status when the proxy is not running; that report is on stdout.

Exit 2 means an unknown option, an option missing its value or a stray argument. For isx proxy status only, 2 also means the proxy is down but its DNS overrides are still active.