FAQ Setup and Operation

FAQ: Setup and Operation

Common questions about platform support, configuration, and day-to-day use.

Can I run COI on Windows?

Not directly. Incus is Linux-only. However, you can:

1. WSL2 (Windows Subsystem for Linux) - Install a Linux distribution in WSL2, then install Incus and COI inside WSL2
2. VM - Run a Linux VM (Ubuntu, Debian, etc.) and install COI there

Note: Windows support via WSL2 is experimental and not officially tested. Linux or macOS (via Colima/Lima) are the recommended platforms.

Why does COI use Colima on macOS? Can I use Incus directly?

Incus requires a Linux kernel - LXC (Linux Containers) is a Linux kernel feature. On macOS, a Linux VM is needed to run Incus.

• On Linux: COI uses Incus directly. No Colima, no VM layer.
• On macOS: Colima (or Lima) provides a lightweight Linux VM where Incus runs. COI manages the VM transparently.

If you're on Linux, there's no Colima involved. See the macOS Setup Guide for macOS-specific instructions.

Is this really simpler than just running Claude Code directly?

First-time setup: coi build (one time, 5-10 minutes), then coi shell - that's it.

After setup: Just cd your-project && coi shell - same simplicity as running Claude Code directly, but with:

• ✅ Automatic file ownership (no permission issues)
• ✅ Credential isolation (your SSH keys stay safe)
• ✅ Session save/resume (continue later)
• ✅ Parallel sessions (multiple workspaces/slots)
• ✅ Clean environment (no host pollution)

The complexity is hidden. You get security and isolation with the same simple workflow.

What is Incus? (Is it the same as tmux?)

No, Incus is not tmux. They're completely different tools.

Incus - Linux container and VM manager (like Docker, but for system containers):

• Manages containers with full operating systems inside
• Provides isolation, networking, storage, etc.
• COI uses Incus to create isolated environments

tmux - Terminal multiplexer for managing shell sessions:

• Lets you detach/reattach terminal sessions
• COI uses tmux inside containers to manage AI tool sessions

In COI: Incus creates the container, tmux runs inside it to manage your session with the AI tool.

Can I preserve the workspace path inside the container?

Yes. By default, your project is mounted at /workspace inside the container. If you need the container workspace to use the same absolute path as on your host (useful for tools that store session data relative to the workspace directory), enable preserve_workspace_path:

# .coi/config.toml or ~/.coi/config.toml
[paths]
preserve_workspace_path = true

With this enabled, if your project is at /home/user/projects/my-app, it will be mounted at the same path inside the container.

Can I use Docker and Docker Compose inside COI?

Yes. COI automatically enables Docker support flags (security.nesting, security.syscalls.intercept.mknod, security.syscalls.intercept.setxattr) on session containers. Docker and Docker Compose work out of the box without any additional configuration.

Docker commands also work without sudo - the container's code user is added to the docker group, and the Docker socket is configured with the correct group ownership.

If Docker commands fail, verify that:

1. Your COI image was built with the latest coi build
2. You're using coi shell (not raw incus exec)

How do I add extra context files (agents, rules, configs) into my container?

Use [[mounts.default]] in your config to mount host directories into the container. The key rule is: mount subdirectories, not the parent config directory (e.g., mount ~/.claude/skills, not ~/.claude).

See the Configuration - Mounting Additional Files section for full examples, common patterns (Claude skills/commands/plugins, opencode agents), and security guidance.

Why run an AI agent locally instead of in the cloud?

AI coding agents are most effective when they can:

• Access your actual project files and directory structure
• Run your test suite and build tools
• Interact with local services (databases, APIs)
• Use your project's Docker Compose setup
• Work with low latency and no network dependency

Running in the cloud adds latency, requires syncing files, and complicates access to local development services. COI's approach is: run locally but contained - you get the convenience of local execution with the safety of isolation and security monitoring.

Can I use COI with local/self-hosted AI models?

COI supports multiple AI coding tools through its extensible tool interface. Currently supported:

• Claude Code (default) - Anthropic's CLI agent
• opencode - open-source AI coding agent

Coming soon:

• Aider - AI pair programming tool
• Cursor (CLI mode)

See Supported Tools for the full list and configuration details.

Adding support for other tools (including those backed by local models like Ollama) is possible by implementing the tool interface. If you'd like to see a specific tool supported, open an issue.

More Questions?

Join the COI community on Slack for live discussion and support.

---

See Also

• Getting Started - Step-by-step setup and first session walkthrough
• Configuration - Full configuration reference
• Supported Tools - AI tool options and configuration
• FAQ - Return to the FAQ index