How It Works
code-on-incus (coi) isolates AI agents within full-OS Linux containers using Incus, providing each agent with root access, systemd, Docker, and the ability to install packages or run services—just as it would on a dedicated server. Unlike traditional sandboxing methods, coi does not restrict agents to a locked-down environment. Instead, it ensures the host system remains untouched by design: agents cannot access host credentials, SSH keys, or environment variables unless explicitly configured. This isolation is enforced at the kernel level, with real-time threat detection that automatically pauses or terminates containers exhibiting suspicious behavior, such as reverse shells, command-and-control connections, or data exfiltration attempts.
The tool operates on Linux natively, with macOS support via Colima or Lima, and relies on Incus’s system containers to deliver a near-native experience. Each container runs as an independent instance, complete with its own filesystem, networking stack, and process management. Workspace files are mounted into the container with correct ownership, ensuring seamless file operations without manual permission adjustments. Changes made inside the container are automatically synced back to the host, preserving the developer’s workflow while maintaining strict isolation.
At its core, coi uses kernel-level monitoring via nftables to enforce network policies and detect threats in real time. Credentials and sensitive files are never exposed by default, though they can be selectively forwarded via host sockets or short-lived tokens. This approach ensures that even if an agent is compromised, the host system remains secure.
Containers can be ephemeral, deleting all traces upon exit, or persistent, retaining installed packages and running services between sessions. Persistent containers are identified by a session name, allowing multiple tools to reuse the same environment while maintaining separate configurations and session histories.
Configuration is managed through profiles, which bundle container settings—such as image, resource limits, mounts, and network policies—into reusable templates. The hardened profile, for example, enforces strict lockdowns: restricted networking, workspace secret masking, ephemeral containers, and active threat monitoring. This preset is ideal for inspecting untrusted code safely, as it minimizes attack surfaces while maintaining functionality.
Every command in coi is designed for simplicity and automation. Starting a session requires three steps: installation via a one-liner, building the base image (a one-time process), and launching the agent from any project directory. Common operations—such as running commands, monitoring resources, or auditing security events—are accessible via CLI flags. For automation, coi supports headless prompt execution, where agents process predefined tasks without interactive input, making it suitable for cron jobs or CI/CD pipelines.
Under the hood, coi leverages Incus’s lightweight virtualization to create containers that are more efficient than full virtual machines but offer similar isolation guarantees. The tool’s architecture ensures that even if an agent escapes its container (a rare but possible scenario), the host’s kernel-level protections limit the damage. This combination of isolation, monitoring, and automation makes coi a practical solution for developers who need to run untrusted or experimental AI agents without compromising their primary system.
Use Cases
code-on-incus is primarily designed for developers and security-conscious teams who run AI coding agents—such as Claude Code, Codex CLI, or Oh My Pi—while requiring full machine access without risking the host environment. One key use case is running multiple agents in parallel, each isolated from one another, to prevent cross-contamination between projects or experiments.
When reviewing or modifying code from external sources, developers can spin up a hardened container with restricted networking and automatic threat detection. The hardened profile ensures that even if the agent is compromised, sensitive credentials or network access remain protected. This is particularly valuable in open-source contributions, security audits, or when evaluating third-party tools where trust levels are uncertain.
Automation is a third major use case, where coi enables headless execution of AI agents for repetitive tasks. For instance, a developer might configure a nightly maintenance prompt to update dependencies, run tests, and open pull requests if the tests pass. By scheduling these tasks via cron, coi allows for fully automated workflows without manual intervention. The tool’s support for predefined prompts and persistent containers ensures that complex, multi-step processes can be executed reliably, with exit codes propagated to the host for logging or alerting.
A team might define a profile for their development environment, including specific tools, resource limits, and network policies. This profile can then be shared across the team, ensuring consistency in how agents are deployed and reducing the risk of misconfigurations. For example, a Python development profile might include preinstalled dependencies, a restricted network mode, and automated security checks, all applied with a single command.
Security researchers and penetration testers also find value in coi, as it provides a controlled environment for testing AI agents against malicious inputs or adversarial scenarios. The tool’s real-time threat detection and automatic containment allow researchers to observe agent behavior without fear of host compromise. For instance, a tester might use coi to evaluate how an AI agent responds to crafted prompts designed to trigger unauthorized actions, with the tool automatically pausing or killing the container if suspicious activity is detected.
Finally, coi is useful for educational purposes, where students or learners can experiment with AI agents in isolated environments without affecting their primary systems. Instructors can distribute predefined profiles for specific courses or exercises, ensuring that all participants start with the same secure setup.
Isolation and Security
code-on-incus provides full-OS containerization through Incus, giving each AI agent a dedicated Linux environment with root access, systemd, and Docker. This level of isolation ensures that agents operate as they would on a real server, with the ability to install packages, manage services, and use cron—all without risking the host system. Credentials, SSH keys, and environment variables are never exposed by default, though they can be selectively forwarded when needed.
The tool’s active defense mechanism monitors containers for threats in real time, using kernel-level checks to detect reverse shells, command-and-control connections, data exfiltration, and credential scanning. When high-risk activity is detected, coi automatically pauses the container (for investigation) or terminates it entirely (for critical threats). This proactive approach eliminates the need for manual monitoring, reducing the window of exposure during potential breaches.
Credential and Workspace Protection
coi ensures that sensitive files—such as SSH keys, .env files, and Git tokens—remain isolated from agent-controlled environments. Instead of mounting these files directly, developers can forward host sockets or generate short-lived tokens per session. Workspace files are mounted with correct ownership, eliminating the need for manual chown operations and ensuring seamless file operations between the host and container. Changes made inside the container are automatically synced back to the host, preserving the developer’s workflow while maintaining strict isolation.
Persistent and Ephemeral Containers
Containers in coi can be configured as persistent or ephemeral. Persistent containers retain installed packages, running services, and session history between uses, making them ideal for long-running development environments. Each persistent container is identified by a session name, allowing multiple tools to reuse the same environment while maintaining separate configurations.
Ephemeral containers, on the other hand, delete all traces upon exit, ensuring no residual data remains after a session ends. This mode is useful for one-time tasks or when working with untrusted code, as it guarantees a clean slate for each new session. The hardened profile, which enforces strict lockdowns, is often used with ephemeral containers to minimize attack surfaces while inspecting potentially malicious code.
Profiles and Automation
Profiles are a central feature of coi, allowing developers to bundle container settings—such as image, resource limits, mounts, and network policies—into reusable templates. A profile can include everything from tool-specific configurations to build scripts and AI-agent instructions. For example, a Rust development profile might specify a custom image with Rust toolchain preinstalled, resource limits to prevent excessive memory usage, and a restricted network mode to block outbound connections except to trusted domains.
The hardened profile, for instance, overrides weaker global configurations to enforce maximum security, including restricted networking, workspace secret masking, and automatic threat monitoring. This preset requires no additional setup and is ideal for inspecting untrusted repositories safely.
Automation is further enhanced through headless prompt execution, where coi runs AI agents to completion without interactive input. This capability is particularly useful for cron jobs or CI/CD pipelines, where predefined tasks—such as updating dependencies or running tests—can be executed automatically.
Supported AI Tools and Interoperability
coi natively supports several AI coding tools, including Claude Code (default), Codex CLI, opencode, Oh My Pi (omp), and Aider (in development). Tool selection is configured via profiles or global settings, with each tool maintaining its own session history and credentials.
This allows external orchestrators to drive supported tools without reimplementing their CLI interfaces. Additionally, coi integrates with OrbStack, Colima, and Lima for macOS support, expanding its compatibility across different operating systems.
Resource Monitoring and Management
This visibility helps developers identify resource-intensive processes and take corrective action, such as terminating runaway containers. Resource limits can be enforced per container, including disk quotas to prevent storage exhaustion.
The tool also addresses common issues in container management, such as firewall rule bloat on NetworkManager + firewalld systems. coi automatically detects and mitigates leaks in the firewall ruleset, ensuring stable performance even with frequent container churn. Firewall teardown fixes have been implemented to clean up orphaned IPv6 blocks and other residual resources, preventing long-term degradation of system performance.
Supply-Chain and Configuration Protections
Configuration symmetry allows settings—such as mounts, environment variables, and network policies—to be defined in either global or profile-specific contexts.
Compatibility and Extensibility
coi is designed to work seamlessly with existing workflows, supporting Linux natively and macOS via OrbStack, Colima, or Lima. The tool’s architecture is built on Incus, a lightweight virtualization platform that offers near-native performance while maintaining strong isolation guarantees.
Extensibility is a key feature, with support for custom build scripts, tool-specific configurations, and reusable prompts. Developers can extend coi’s functionality by defining their own profiles, integrating with external systems via JSONL audit logs, or automating workflows using headless prompt execution. The tool’s MIT license further encourages community contributions, ensuring that it remains adaptable to evolving use cases in AI and security.
Supported AI Tools and Configuration
code-on-incus supports a growing list of AI coding tools, each configurable through profiles or global settings. The default tool is Claude Code, but users can switch between supported tools—such as Codex CLI, opencode, Oh My Pi (omp), and upcoming tools like Aider and Cursor—without losing state. Tool selection is defined in configuration files (e.g., ~/.coi/config.toml or .coi/config.toml) under the [tool] section, where the name field specifies the active agent.
would configure the container to use OpenAI’s Codex CLI instead of Claude Code.
For instance, a developer might create two profiles—box-claude and box-codex—both targeting the same `sessionname =
Headless execution is another key feature, enabling automation through predefined prompts. The coi run --prompt command processes a prompt to completion without interactive input, making it ideal for cron jobs or CI/CD pipelines. For example, a nightly maintenance prompt might update dependencies, run tests, and open a pull request if successful.
Resource limits can be enforced per container, including disk quotas to prevent runaway processes from exhausting storage. These controls ensure that even if an agent is compromised, the host system remains protected.
Profiles play a central role in coi’s configuration system, allowing developers to bundle settings—such as image, resource limits, mounts, and network policies—into reusable templates. A profile can include everything from tool-specific configurations to build scripts and AI-agent instructions. For example, a hardened profile might enforce restricted networking, workspace secret masking, and automatic threat monitoring, making it ideal for inspecting untrusted code.
The tool’s command-line interface is designed for simplicity and automation. Common operations—such as starting a session, running commands, monitoring resources, or auditing security events—are accessible via CLI flags. For instance, coi shell launches an interactive session with the default tool, while coi run --prompt executes a predefined task headlessly.
Advanced Features and Optimizations
One such feature is the coi health command, which checks for common issues—such as firewall rule bloat on NetworkManager + firewalld systems—and provides remedies. For example, if container churn causes the firewall ruleset to grow excessively, coi health detects the problem and suggests corrective actions, such as reloading firewalld or configuring NetworkManager to exclude container interfaces.
Firewall teardown fixes have been implemented to address leaks in the nftables ruleset, ensuring that orphaned resources—such as IPv6 egress blocks—are cleaned up during container shutdown.
Named sessions are another advanced feature, allowing containers to persist across workspace moves. By setting a session_name in a profile (paired with persistent = true), developers can reuse the same container from any directory, with workspace mounts reconciled automatically. This ensures that session history, configurations, and running services remain intact even if the project is relocated.
OrbStack support extends coi’s compatibility to macOS, joining Colima and Lima as fully supported alternatives for non-Linux environments.
Configuration symmetry allows settings—such as mounts, environment variables, and network policies—to be defined in either global or profile-specific contexts. Similarly, environment variables and command timeouts can be set per profile, enabling fine-grained control over container behavior.
Each log entry includes detailed information about detected threats—such as reverse shells, data exfiltration attempts, or credential scanning—along with timestamps and container identifiers. This data enables post-mortem analysis and helps developers understand how agents interact with their environments.
Extensibility is a key aspect of coi’s architecture, with support for custom build scripts, tool-specific configurations, and reusable prompts. Developers can extend the tool’s functionality by defining their own profiles, integrating with external systems via JSONL audit logs, or automating workflows using headless prompt execution.