[opensourcedex]

code-on-incus is a free, open source ai security & privacy project written in Go and released under MIT. It has 720 GitHub stars, 62 forks and 24 open issues, and was last pushed 2 days ago. On this registry it ranks #31 of 34 tracked projects in AI Security & Privacy, with 5 head-to-head comparisons available. It gained 14 stars over the last 3 tracked days.

What is code-on-incus?

code-on-incus (coi) is an MIT-licensed Go tool that runs AI coding agents such as Claude Code, Codex, opencode, pi, and omp inside their own isolated Incus system containers — full Linux machines with root, systemd, and Docker — and adds kernel-level active defense that pauses or kills the container when it detects dangerous behavior, for developers who need real machine access without exposing the host or their credentials.

What it is

code-on-incus is a command-line tool written in Go and distributed under the MIT licence. It gives each AI coding agent an isolated Linux system container, using Incus as the isolation layer rather than a conventional Docker sandbox. The container is a full operating system with systemd, root access, native Docker, and package managers, so an agent can install software, run services, and use cron as it would on a real server. The project directory is mounted at /workspace with correct file ownership, and workspace changes are saved back to the host. It sits in the AI & Machine Learning / AI Security & Privacy category, with topics including agentic-ai, claude-code, codex, code-sandbox, container-security, and incus.

The problem it solves is the tension between giving an AI coding agent enough access to do useful work and keeping that agent away from the host and its secrets. Running an agent directly on a development machine exposes SSH keys, .env files, Git tokens, and host environment variables; running it in a Docker sandbox often creates permission and file-ownership problems, which the README calls permission hell. code-on-incus replaces both the bare-metal pattern and the Docker sandbox pattern for agent execution. The agent gets a real machine, but it cannot touch the host, cannot see credentials unless they are explicitly mounted, and is monitored for dangerous behavior while it runs. The project describes itself as a tool, not a product or a startup.

Key capabilities

  • coi shell starts a coding session from any project directory, mounts the project at /workspace, and writes files with correct ownership so no chown step is needed.
  • Incus system containers run a full OS with systemd and native Docker, allowing agents to install packages, run services, and use cron like a server.
  • SSH keys, .env files, Git tokens, and host environment variables never enter the container unless explicitly mounted; secrets can be supplied through a forwarded host socket or a short-lived per-session token.
  • Kernel-level monitoring catches reverse shells, C2 connections, data exfiltration, DNS tunneling, and credential scanning in real time, with auto-pause on HIGH and auto-kill on CRITICAL.
  • Parallel sessions can run on the same project at once, and each slot gets its own home directory so nothing leaks between them.
  • Containers can be ephemeral or persistent, but workspace files and session history are always saved, and a session can be resumed with conversation history and credentials restored.
  • coi build creates the base image on first use, taking roughly five to ten minutes, after which Docker and gh are available inside the container.

Who uses it and how

  • Developers who run Claude Code, Codex, opencode, pi, or omp and need root, Docker, package managers, and services without risking the host machine.
  • Teams running multiple agents in parallel on one project and needing each session isolated from the others.
  • Developers who want persistent dev environments that survive restarts instead of throwaway containers that lose their setup.
  • Security-conscious users who need credentials to stay outside any agent-controlled environment.
  • Linux users with Incus installed, plus macOS users running Incus through Colima or Lima.

Getting started

Install with the project's shell installer at https://raw.githubusercontent.com/mensfeld/code-on-incus/master/install.sh, then run coi build once to create the base image and coi shell from a project directory to start a session. It requires Linux with Incus; macOS is supported through Colima or Lima.

How it compares

The README positions coi against Docker Sandbox and bare metal rather than against paid products. Docker Sandbox is presented as a locked box with permission and file-ownership problems, while bare metal leaves the agent with no isolation from the host at all; coi uses Incus system containers to give the agent a full OS with systemd and native Docker without host access.

When to use it — and when not to

A self-hoster must operate an Incus host and build the base image, which takes roughly five to ten minutes on first run, and no hosted or managed option is described. Developers who cannot run Incus, or who want a fully managed cloud service, should not choose this tool. The macOS path depends on Colima or Lima rather than native Incus, and the repository carries 24 open issues.

project readme (upstream, from github) — read inline

code-on-incus (coi)

License: MIT Go Version Latest Release Join the chat at https://slack.karafka.io

Give every AI coding agent its own machine - with active defense.

coi runs your AI coding tool (Claude Code, Codex, opencode, pi, omp) inside its own isolated Linux system - a full-OS container with root access, systemd, Docker, and the freedom to install anything. The agent works like it would on a real server - but it can't touch your host, can't see your credentials, and if it does something dangerous, coi pauses or kills the container on its own.

One command drops you into a coding session. Your project is mounted, file permissions just work, and your SSH keys, tokens, and environment variables never enter the container unless you explicitly say so.

Built by developers, for developers who run AI agents and want to know what those agents are doing. Not a product, not a startup - a tool that does the job.

BetterStack video about Code on Incus
Watch the BetterStack video about Code on Incus

Demo

Get started in three commands

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

# 2. Build the base image (first time only, ~5-10 min)
coi build

# 3. Start coding - from any project directory
cd your-project
coi shell

That's it. Your agent is now running in an isolated container with your project at /workspace, correct file ownership (no more chown), Docker and gh available inside, every workspace change saved back to the host - and no access to your host SSH keys, env vars, or credentials.

Requires Linux with Incus (macOS works too, via Colima/Lima - see macOS Setup).

Who it's for

  • You run AI coding agents and want them to have full machine access - root, Docker, package managers, services - without risking your host.
  • You want to know when an agent does something suspicious, not find out after the fact.
  • You run multiple agents in parallel and need them isolated from each other.
  • You want persistent dev environments that survive restarts, not throwaway containers that lose your setup every time.
  • You care about your credentials never ending up inside an agent-controlled environment.

What makes it different

  • A real machine, not a locked box. Incus system containers run a full OS with systemd and native Docker inside. Agents install packages, run services, use cron - exactly like a server, with none of Docker's permission hell (files come out correctly owned).

  • Your credentials stay home. SSH keys, .env files, Git tokens, and host environment variables are never exposed unless you explicitly mount them. Need to give an agent a secret? Forward a host socket or mint a short-lived token per session - the secret itself never enters the container.

  • Active defense, not just a wall. Kernel-level monitoring catches reverse shells, C2 connections, data exfiltration, DNS tunneling, and credential scanning in real time - and auto-pauses on HIGH, auto-kills on CRITICAL. No babysitting.

  • Parallel agents, fully isolated. Run several sessions on the same project at once; each slot gets its own home directory, so nothing leaks between them.

  • Your work always survives. Containers can be ephemeral (deleted on exit) or persistent (kept with installed packages) - either way, workspace files and session history are always saved. Resume any session later with full conversation history and credentials restored.

coi vs. the alternatives

Capability code-on-incus Docker Sandbox Bare Metal
Credential isolation Default (never exposed) Partial None
Real-time threat detection Kernel-level (nftables) No No
Reverse-shell / exfil response Auto-kill / auto-pause No No
Network isolation nftables (3 modes) Basic No
Supply-chain protection Git hooks / IDE configs read-only No No
Audit logging JSONL forensics No No
Runs on Linux natively Yes microVM only on macOS/Windows -

Profiles: your setups, one flag

Profiles are the feature you'll reach for every day. A profile is a reusable, named container setup - image, tool, resource limits, mounts, network mode, build scripts, and AI-agent instructions bundled into one template you can apply with a single flag.

coi shell --profile rust-dev        # spin up your Rust environment, ready to go
coi profile create rust-dev         # scaffold a new profile, then edit its config.toml
coi profile list                    # see what you've got

Profiles support inheritance (inherits = "parent"), ship AI-agent context files, and can carry their own build scripts - so "my hardened Python box with these limits and these tools" becomes one word.

The killer preset: hardened. Opening a repo you don't trust? One flag gives you coi's strongest lockdown - restricted network (no exfil path), workspace secret masking, an ephemeral container, no SSH-agent forwarding, and live threat monitoring with auto-pause/kill:

coi shell --profile hardened        # inspect untrusted code safely
coi profile info hardened           # see exactly what it locks down

It overrides a weaker global config (a global mode = "open" still becomes restricted) and needs zero setup. See the Profiles wiki page for the full reference and schema.

Supported AI tools

Claude Code (default) · Codex CLI · opencode · pi · omp (Oh My Pi) - pick one in config or a profile:

# ~/.coi/config.toml or ./.coi/config.toml
[tool]
name = "claude"              # or "codex", "opencode", "pi", "omp"
permission_mode = "bypass"   # run autonomously ("bypass") or ask first ("interactive")

Switching tools on the same container. Tool choice is config/profile-shaped, not a per-command flag. To re-enter one persistent container (same code, packages, and running services) with a different tool, give two profiles the same [container] session_name — a container's identity is hash(workspace, session_name), so they resolve to the same box:

# ~/.coi/profiles/box-claude/config.toml        # ~/.coi/profiles/box-codex/config.toml
[container]                                      # [container]
persistent = true                                # persistent = true
session_name = "box"                             # session_name = "box"
[tool]                                           # [tool]
name = "claude"                                  # name = "codex"

coi shell --profile box-claude    # create/enter the "box" running claude
coi shell --profile box-codex     # re-enter the SAME box running codex

On reuse, coi seeds the re-entering tool's credentials/config the first time that tool is used in the box (without disturbing the other tool's config or history). Session history is per-tool (~/.coi/sessions-), so --resume/--continue resume that tool's own conversations.

Aider and Cursor are on the way. See the Supported Tools wiki page for per-tool auth and configuration.

Everyday commands

coi shell                 # interactive AI session (Claude Code by default)
coi run -- npm test       # run any command in the sandbox (streams output, propagates exit code)
coi run --prompt-name nightly   # fire-and-forget: run the agent headlessly from a predefined prompt
coi top                   # per-container CPU/memory/IO, resolved to workspace + alias
coi monitor               # real-time security dashboard
coi list --all            # active containers + saved sessions
coi attach                # attach to a running session
coi audit                 # stream the JSONL threat-event log (pipe into a SIEM or jq)
coi shutdown / coi kill   # stop or force-kill containers
coi clean                 # remove stopped containers and orphaned resources

Drop a .coi/config.toml in any repo to au

readme truncated — read the full docs on github

Frequently asked questions

Is code-on-incus free to use?

code-on-incus is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does code-on-incus do?

Give each AI agent its own isolated machine with root, Docker, and systemd. Active defense detects and stops threats automatically.

What is code-on-incus written in?

code-on-incus is primarily written in Go. Its source is publicly available at https://github.com/mensfeld/code-on-incus, and it has 720 GitHub stars.