Release v0.13.0

Installation

Quick Install (Linux)

# Install latest version
curl -fsSL https://raw.githubusercontent.com/mensfeld/code-on-incus/master/install.sh | bash

Manual Installation

Download the appropriate binary for your system:

Linux AMD64 (x86_64)

wget https://github.com/mensfeld/code-on-incus/releases/download/v0.13.0/coi-linux-amd64
chmod +x coi-linux-amd64
sudo mv coi-linux-amd64 /usr/local/bin/coi

Linux ARM64 (aarch64)

wget https://github.com/mensfeld/code-on-incus/releases/download/v0.13.0/coi-linux-arm64
chmod +x coi-linux-arm64
sudo mv coi-linux-arm64 /usr/local/bin/coi

Verify Installation

coi version
coi build sandbox
coi shell

What's Changed

See CHANGELOG.md for full changes.

Requirements

• Incus - Linux container manager
• Go 1.26+ - For building from source
• incus-admin group - User must be in incus-admin group

Documentation

• README
• Wiki
• CHANGELOG

Release v0.12.0

code-on-incus v0.12.0

An additive release — no breaking changes, no config migration. Everything below is opt-in; existing configs and profiles keep working after coi update.

Highlights

• Switch AI tools inside one persistent container. Point two profiles at the same [container] session_name and each re-enters the same box under its own [tool] name — keep your code, packages, and running services while moving between Claude Code, Codex, and others. The new tool's credentials are seeded on first switch.
• Headless "fire and forget" prompt runs. coi run --prompt "…" (or --prompt-file / --prompt-name) runs the agent to completion on a predefined prompt and exits with its status code — the building block for cron automation. Register reusable prompts in a [prompts] table.
• coi top — live per-container (and per-process) CPU / memory / disk / network usage, so you can see what's loading your machine and kill a runaway by host PID.
• Two new tools: OpenAI Codex CLI ([tool] name = "codex") and Oh My Pi (omp), both opt-in at image build via [container.build] agents.

New features

• coi tool spec — print a tool's exact launch command + env for an external orchestrator to drive any supported tool without reimplementing its CLI.
• [limits.disk] size — cap a container's entire root filesystem from a profile (e.g. "20GiB"); the simplest way to stop a runaway build or /tmp from filling the disk.
• ~/SANDBOX_CONTEXT.json — a structured JSON companion to the Markdown sandbox context, for programmatic consumers.
• --json on every command that offers --format text|json.
• Tighter egress control — per-host ports on [[network.hosts]], per-destination :ports in allowed_domains, [network] dns_servers, and [network] allowed_ports.
• [git] readonly = true — lock the container's git commit identity so the agent can't change who commits are authored by.

Changed

• Config/profile symmetry. A [mounts] block now works in both the flat [[mounts]] and nested [[mounts.default]] form in either top-level config or a profile — copy it between them verbatim. env_command_timeout is now settable per profile.
• Leaner injected sandbox context (~30% fewer per-session tokens), and more reliable case-insensitive container-status checks.

Notable fixes

• coi build works on a non-default [incus] project — no more "image not found" right after a successful publish.
• coi shell works under kitty and similar terminals (xterm-kitty, foot, rio, contour, st-*) — the env TERM=xterm-256color workaround is gone.
• permission_mode = "interactive" keeps Claude Code's in-session auto-mode toggle selectable.
• coi run now gets the same hardening as coi shell (NIC anti-spoofing, boot-window egress block, IPv6 disable, credential seeding, git-identity lock).
• coi shell honors [container] storage_pool; [limits.disk] tmpfs_size actually resizes /tmp; the security monitor no longer false-freezes a healthy container on an I/O-counter blip; and a running container no longer blocks host suspend.

Full details: CHANGELOG · Docs: Wiki (updated for 0.12) · Upgrading: Migration Guide

---

Installation

Quick Install (Linux)

# Install latest version
curl -fsSL https://raw.githubusercontent.com/mensfeld/code-on-incus/master/install.sh | bash

Manual Installation

Download the appropriate binary for your system:

Linux AMD64 (x86_64)

wget https://github.com/mensfeld/code-on-incus/releases/download/v0.12.0/coi-linux-amd64
chmod +x coi-linux-amd64
sudo mv coi-linux-amd64 /usr/local/bin/coi

Linux ARM64 (aarch64)

wget https://github.com/mensfeld/code-on-incus/releases/download/v0.12.0/coi-linux-arm64
chmod +x coi-linux-arm64
sudo mv coi-linux-arm64 /usr/local/bin/coi

Verify Installation

coi version
coi build sandbox
coi shell

What's Changed

See CHANGELOG.md for full changes.

Requirements

• Incus - Linux container manager
• Go 1.25+ - For building from source
• incus-admin group - User must be in incus-admin group

Documentation

• README
• Wiki
• CHANGELOG

Release v0.11.2

code-on-incus v0.11.2

A patch release for hosts running NetworkManager + firewalld, where container churn could quietly grow the firewall ruleset past 100,000 rules — plus firewall teardown fixes for everyone. Drop-in upgrade, no breaking changes.

📦 Install / upgrade

coi update

# Or fresh install — Linux amd64 (use coi-linux-arm64 on aarch64)
wget https://github.com/mensfeld/code-on-incus/releases/download/v0.11.2/coi-linux-amd64
chmod +x coi-linux-amd64 && sudo mv coi-linux-amd64 /usr/local/bin/coi
coi version

🔥 firewalld veth zone bloat — detected and prevented (#695)

On NM+firewalld hosts, NetworkManager enrolls each container's host-side veth into firewalld's default zone. The registration leaks when the container is deleted, and firewalld generates its FORWARD policy rules as the cross product of zone interfaces — so the ruleset grows with the square of leaked veths. The reporting host had 145 dead veths ≈ 101,888 rules while coi's own tables held ~50.

• coi health now runs a firewalld_veth_bloat check: it counts dead veth registrations and warns with both remedies — sudo firewall-cmd --reload to collapse the bloat now, and an NM unmanaged-devices+=interface-name:veth* drop-in to stop the enrollment. (Verify your Incus bridge is in the trusted zone permanently before reloading — the Troubleshooting guide has the safe sequence.)
• install.sh installs that drop-in automatically where NetworkManager is present — carefully: += so a user's own exclusion list is never replaced, active-rule detection so an existing setup is respected, fully best-effort, and skippable with COI_SKIP_NM_UNMANAGED=1. Manual installs: see the wiki's Linux Setup Guide.

🧹 Firewall teardown fixes (#696, first installment)

An audit of coi's nft rule lifecycle fixed the three sharpest leaks:

• coi kill and coi shutdown now remove the container's IPv6 egress block rule (previously leaked by both paths — it's name-keyed, so it's removed even when the container's IP was unresolvable).
• coi clean --orphans no longer reports "no orphaned resources found" when leaked IPv6 blocks are the only orphan class (they were missing from the count).
• Reaping is fast everywhere: a never-created nft chain (e.g. IPv6 in open network mode) or disabled sudo no longer spins an 8-round retry loop (~2s + 8 warnings per container) — and the health check's orphan hint now points at coi clean --orphans, the variant that actually cleans firewall state.

The deeper lifecycle work (monitoring-rule idempotency, allowlist set-element pruning, default-clean firewall cleanup) is tracked in #696.

What's Changed

See CHANGELOG.md for full details.

Documentation

• README
• Wiki
• CHANGELOG

Release v0.11.1

code-on-incus v0.11.1

A patch release with two headline additions — named sessions that survive workspace moves, and first-class OrbStack support — plus a health check that names the single biggest startup cost, and fixes for self-update and sandbox-context growth. No breaking changes; upgrading is drop-in.

📦 Install / upgrade

# Upgrade an existing install
coi update

# Or fresh install — Linux amd64 (use coi-linux-arm64 on aarch64)
wget https://github.com/mensfeld/code-on-incus/releases/download/v0.11.1/coi-linux-amd64
chmod +x coi-linux-amd64 && sudo mv coi-linux-amd64 /usr/local/bin/coi
coi version

Note: the v0.11.0 release binary had a bug that made coi update wrongly report "already on the latest version" (#673). If coi update claims you're current, upgrade once manually (commands above) — from this release on it works again.

✨ Named sessions — [container] session_name (#693)

Session identity (the container a launch attaches to, slot/port allocation, and the saved history --resume/--continue finds) was always keyed on the workspace path — moving a checkout meant a fresh container and unreachable history. Setting session_name (typically in a profile, paired with persistent = true) keys everything on the name instead:

# ~/.coi/profiles/myproj/config.toml
[container]
persistent = true
session_name = "myproj"

The same session now continues from any workspace location, with the workspace mount reconciled automatically on reuse. Honored from trusted scope only — a cloned repo's .coi cannot attach itself to your session (including via profile inheritance). Attaching to a running named session that still mounts a different checkout is refused, forking a busy name warns loudly, and adopting a name over an existing workspace carries your saved conversation history forward. See Named Sessions in the wiki.

🍎 OrbStack support & the idmapped-mount arc (#678, #683, #685 — thanks @technicalpickles)

OrbStack joins Colima/Lima as a fully supported macOS option, and the underlying UID-mapping machinery got a rework driven by three excellent reports:

• Proactive filesystem check (#683): before starting a container, coi statfs's every disk-device source (workspace, [[mount]]s, a git worktree's external git dir — missing paths judged by their nearest existing ancestor) and skips Incus's idmapped (shift=true) mounts for FUSE-family and 9p sources, using raw.idmap instead. This fixes OrbStack ≥ 2.2.2's silent failure mode, where the share accepted idmapped mounts but mapped ownership wrongly — the container started clean and every /workspace write failed (upstream: orbstack/orbstack#2530).
• Reactive fallback everywhere (#678, #685): a start failing with idmapping abilities are required but aren't supported on system auto-converts to raw.idmap and retries — now on every start path, including reused persistent containers (which also no longer re-arm the broken config each session). Pre-upgrade containers are healed on their next reuse.
• disable_shift is now a rarely-needed manual override; the macOS Setup Guide has a full OrbStack section.

🩺 coi health names the slow-startup culprit (#659 — thanks @technicalpickles)

A dir-driver storage pool re-unpacks the whole container image on every launch (~5-6s per unpacked GB — 73% of a coi run on the reporting host). coi health now reports each pool's driver (default (zfs): 77.5 GiB free …) and warns outright on dir pools with the fix (recreate with zfs/btrfs — install.sh sets one up). Enumerated pools with failed usage queries now say usage unavailable instead of the misleading missing.

🔧 Also fixed

• Sandbox context no longer grows ~/.claude/CLAUDE.md (#674): the injected block is marker-delimited and idempotent — one fresh copy per session, and files bloated by older versions (one report: 16 copies, past Claude Code's 40k limit) heal automatically on the next session.
• coi version / coi update (#673 — thanks @sklarsa): release binaries no longer print a doubled vv prefix, version comparison is normalized, and the release pipeline now hard-fails on a malformed version string.

📌 Known follow-ups

Tracked for future releases: coi container start doesn't yet apply the proactive mapping decision (#691), non-thin LVM pools escape the dir-style warning (#686), and #659's optional pre-warm/call-batching ideas.

What's Changed

See CHANGELOG.md for full details.

Documentation

• README
• Wiki
• CHANGELOG

Release v0.11.0

code-on-incus v0.11.0

A minor release (breaking config change → minor bump) that hardens the installer's storage setup, makes the network allowlist survive rotating-IP cloud endpoints, adds static host mappings and a no-flag default profile, and finally wires the model setting through to Claude Code.

Upgrading: one breaking change — model moved to [tool.claude]. See the 0.10.1 → 0.11.0 migration guide.

📦 Install / upgrade

# Upgrade an existing install
coi update

# Or fresh install — Linux amd64 (use coi-linux-arm64 on aarch64)
wget https://github.com/mensfeld/code-on-incus/releases/download/v0.11.0/coi-linux-amd64
chmod +x coi-linux-amd64 && sudo mv coi-linux-amd64 /usr/local/bin/coi
coi version

⚠️ Breaking changes

• model moved from the config root / [defaults] to [tool.claude], and is now actually wired (#657). It was previously stored and printed but never reached the tool. It now lives beside effort_level under [tool.claude] and is delivered to Claude Code as ANTHROPIC_MODEL (e.g. [tool.claude] model = "opus" or a full ID like "claude-opus-4-8"). Migration: move model = "..." into a [tool.claude] table. The old location is no longer honored — a profile config with a root model now fails schema validation, and a global [defaults] model is silently ignored. If you never set model, nothing changes.

✨ New features

• [[network.hosts]] + coi hosts — static /etc/hosts entries with mode-aware firewall reachability (#605). Give a container a fixed name→address mapping (an internal DB, a private service) that stays reachable according to the active network mode: open just resolves; restricted punches a targeted allow for a private target; allowlist adds the address to the firewall set (and refuses private/metadata IPs). Metadata/link-local addresses are refused in both enforcing modes (SSRF). Honored from trusted scope only. The same can be done at runtime with coi hosts add|list|remove <container> … (session-scoped).
• [defaults] profile — pick the profile a bare coi uses (#607). profile = "name" under [defaults] makes plain coi launch your chosen profile, while coi --profile default still gives a clean clone of global config. Lowest-precedence source (an explicit --profile, an alias, or a --resume-remembered profile all win); trusted-scope only.
• coi close — alias for coi shutdown (#593). coi close <name> / coi close --all behave exactly like coi shutdown. Echoes the in-container close verb (note: for a persistent container, coi close/coi shutdown deletes it, whereas the in-container close keeps it).
• COI_TIMING_DEBUG — wall-clock startup profiler (#660). COI_TIMING_DEBUG=1 prints a nested timeline of every pipeline phase, incus subprocess, and nft call to stderr at exit, with per-category totals and slowest calls; COI_TIMING_DEBUG_JSON=<path> dumps JSON. Records nothing unless set.

🐛 Fixes

Installer / storage

• The installer no longer auto-installs ZFS on non-apt distros, where the ZFS packages can rebuild and break the initramfs (Arch/EndeavourOS) — ZFS is auto-installed only on apt, used elsewhere only if already present, otherwise the safe in-kernel btrfs is used (#666). Adds a btrfs fallback when ZFS storage can't be created and skips ZFS outright on OrbStack (#661, #662).

Network / allowlist

• Allowlist mode is now enforced at DNS resolution instead of pinning IPs, so it no longer breaks against domains behind rotating IP pools (Vertex, Bedrock, most of the cloud) (#603). Fixes a fail-closed refresh window that blocked the very addresses it was adding, a rotated-out address stranding an in-flight connection, wildcard allowed_domains resolving the wrong domain (now rejected), leaked nft sets on teardown, and a monitor that could flag every legitimate connection as an attack.
• [[network.hosts]] in allowlist mode now honors allow_local_network_access for private targets (#605, reported by @pbarnes-tibco).

UID mapping

• raw.idmap is now set when code_uid is manually matched to the host UID with shift off (OrbStack workaround), fixing a /workspace owned by nobody:nogroup (#667). A code_uid remap no longer aborts setup when a read-only mount lives under /home/code (#608, thanks @technicalpickles).

Shell / lifecycle

• coi run -- <cmd> now runs with HOME/USER set, so ~ and git config --global work (#623).
• coi shell --container <missing> fails fast with a clear error instead of a misleading 30s timeout (#600).
• Hardened close/poweroff cleanup and outside-state detection (#616, #599); a persistent container no longer wedges on restart when a protected path was removed from the workspace (#610); coi kill no longer reports a failure when it loses a delete race for a container it killed (#609).
• /etc/claude-code/managed-settings.json now lands root-owned and world-readable, so Claude Code no longer fails OAuth when the host UID differs from the container's code user (#606, follow-up to #364).

🔒 Security

• A container in allowlist mode can no longer reach any nameserver.
• coi kill no longer fails when the container is already gone, and now reports why a delete failed.

🧪 Testing & CI

• Broad test-suite hardening this cycle: stabilized flaky monitoring, network, shutdown-timing, and health lanes against CI CPU-starvation and daemon-startup races; de-masked previously xfail'd tests so failures turn CI red; added enforcement/adversarial coverage for limits, the trust gate, the allowlist boundary, auto-pause-on-HIGH, and the installer's ZFS-gate (a real-Arch e2e). No product behavior change from these.

---

📖 Full detail in the CHANGELOG · Wiki · Migration guide

Release v0.10.1

Installation

Quick Install (Linux)

# Install latest version
curl -fsSL https://raw.githubusercontent.com/mensfeld/code-on-incus/master/install.sh | bash

Manual Installation

Download the appropriate binary for your system:

Linux AMD64 (x86_64)

wget https://github.com/mensfeld/code-on-incus/releases/download/v0.10.1/coi-linux-amd64
chmod +x coi-linux-amd64
sudo mv coi-linux-amd64 /usr/local/bin/coi

Linux ARM64 (aarch64)

wget https://github.com/mensfeld/code-on-incus/releases/download/v0.10.1/coi-linux-arm64
chmod +x coi-linux-arm64
sudo mv coi-linux-arm64 /usr/local/bin/coi

Verify Installation

coi version
coi build sandbox
coi shell

What's Changed

See CHANGELOG.md for full changes.

Requirements

• Incus - Linux container manager
• Go 1.25+ - For building from source
• incus-admin group - User must be in incus-admin group

Documentation

• README
• Wiki
• CHANGELOG

Release v0.10.0

Installation

Quick Install (Linux)

# Install latest version
curl -fsSL https://raw.githubusercontent.com/mensfeld/code-on-incus/master/install.sh | bash

Manual Installation

Download the appropriate binary for your system:

Linux AMD64 (x86_64)

wget https://github.com/mensfeld/code-on-incus/releases/download/v0.10.0/coi-linux-amd64
chmod +x coi-linux-amd64
sudo mv coi-linux-amd64 /usr/local/bin/coi

Linux ARM64 (aarch64)

wget https://github.com/mensfeld/code-on-incus/releases/download/v0.10.0/coi-linux-arm64
chmod +x coi-linux-arm64
sudo mv coi-linux-arm64 /usr/local/bin/coi

Verify Installation

coi version
coi build sandbox
coi shell

What's Changed

See CHANGELOG.md for full changes.

Requirements

• Incus - Linux container manager
• Go 1.25+ - For building from source
• incus-admin group - User must be in incus-admin group

Documentation

• README
• Wiki
• CHANGELOG

Release v0.9.0

Installation

Quick Install (Linux)

# Install latest version
curl -fsSL https://raw.githubusercontent.com/mensfeld/code-on-incus/master/install.sh | bash

Manual Installation

Download the appropriate binary for your system:

Linux AMD64 (x86_64)

wget https://github.com/mensfeld/code-on-incus/releases/download/v0.9.0/coi-linux-amd64
chmod +x coi-linux-amd64
sudo mv coi-linux-amd64 /usr/local/bin/coi

Linux ARM64 (aarch64)

wget https://github.com/mensfeld/code-on-incus/releases/download/v0.9.0/coi-linux-arm64
chmod +x coi-linux-arm64
sudo mv coi-linux-arm64 /usr/local/bin/coi

Verify Installation

coi version
coi build sandbox
coi shell

What's Changed

See CHANGELOG.md for full changes.

Requirements

• Incus - Linux container manager
• Go 1.25+ - For building from source
• incus-admin group - User must be in incus-admin group

Documentation

• README
• Wiki
• CHANGELOG

Release v0.8.1

Installation

Quick Install (Linux)

# Install latest version
curl -fsSL https://raw.githubusercontent.com/mensfeld/code-on-incus/master/install.sh | bash

Manual Installation

Download the appropriate binary for your system:

Linux AMD64 (x86_64)

wget https://github.com/mensfeld/code-on-incus/releases/download/v0.8.1/coi-linux-amd64
chmod +x coi-linux-amd64
sudo mv coi-linux-amd64 /usr/local/bin/coi

Linux ARM64 (aarch64)

wget https://github.com/mensfeld/code-on-incus/releases/download/v0.8.1/coi-linux-arm64
chmod +x coi-linux-arm64
sudo mv coi-linux-arm64 /usr/local/bin/coi

Verify Installation

coi version
coi build sandbox
coi shell

What's Changed

See CHANGELOG.md for full changes.

Requirements

• Incus - Linux container manager
• Go 1.21+ - For building from source
• incus-admin group - User must be in incus-admin group

Documentation

• README
• PERSISTENT_MODE.md
• Integration Tests

Release v0.8.0

Installation

Quick Install (Linux)

# Install latest version
curl -fsSL https://raw.githubusercontent.com/mensfeld/code-on-incus/master/install.sh | bash

Manual Installation

Download the appropriate binary for your system:

Linux AMD64 (x86_64)

wget https://github.com/mensfeld/code-on-incus/releases/download/v0.8.0/coi-linux-amd64
chmod +x coi-linux-amd64
sudo mv coi-linux-amd64 /usr/local/bin/coi

Linux ARM64 (aarch64)

wget https://github.com/mensfeld/code-on-incus/releases/download/v0.8.0/coi-linux-arm64
chmod +x coi-linux-arm64
sudo mv coi-linux-arm64 /usr/local/bin/coi

Verify Installation

coi version
coi build sandbox
coi shell

What's Changed

See CHANGELOG.md for full changes.

Requirements

• Incus - Linux container manager
• Go 1.21+ - For building from source
• incus-admin group - User must be in incus-admin group

Documentation

• README
• PERSISTENT_MODE.md
• Integration Tests