Coi CLI
Coi is an Incus container CLI that preserves edits on the host under the file owner, even after the environment is removed.
- 777 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- In `bypass` mode, the agent runs commands without confirmation, has container root and can change the host-mounted workspace.
- Explicitly forwarded secrets are available to processes inside the container.
Install
- Works in
Manual install
curl -fsSL https://raw.githubusercontent.com/coipond/coi/master/install.sh | bashInstalls the Coi CLI. This is the README’s first command. Inspect the installer and prepare Incus before running it.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- In `bypass` mode, the agent runs commands without confirmation, has container root and can change the host-mounted workspace.
- Explicitly forwarded secrets are available to processes inside the container.
This is third-party code. Review the repository files before installing.
What it does
Coi is a system-container CLI that prepares a separate Linux environment with system services and a home directory for an agent. The project is mounted inside the container. Edits persist on the host with the original file owner. Containers can be kept between sessions or discarded after use. A profile sets the image, agent, resource limits and network mode. It can be reused across tasks and inherit another profile. Separate environments support parallel work in one project.
Who it is for. Local development-environment engineers whose agents need Docker, system services and dependencies inside a container.
Good fit when
- An agent uses containerized Docker and systemd to test a project.
- Installed dependencies are retained for the next session.
- Parallel agents work with separate home directories.
- Several projects share one resource and network profile.
Not a fit when
- Each task needs a virtual machine with its own kernel.
- The agent must not write to the mounted project.
- You cannot install Incus on Linux or prepare Colima or Lima on macOS.
Example request
Prepare a Coi profile for project tests with restricted networking, show mounts and validate it before launch.Limitations
Linux requires Incus; on macOS, it runs through Colima or Lima, which need to be set up beforehand. System containers share a kernel, so each task does not receive a separate kernel. The workspace is mounted with write access: agent edits persist on the host even after the container is discarded. Host secrets are not forwarded automatically, but explicitly mounted files and forwarded variables are accessible to the agent; inspect the access list before starting a session.
How to disable. Exit the session and stop the container using `coi shutdown`. Inspect dependencies and data that need preserving before cleaning stopped environments.
FAQ
How do I validate a custom profile?
Run `coi schema profile` to get the schema, then `coi validate profile ~/.coi/profiles/<name>/config.toml` with your file path. Unknown keys are errors.
Which network modes are available?
Open, restricted and allowlist modes. A profile selects one alongside the other environment settings.
How do I inspect resource usage?
Use `coi top` for CPU, memory and I/O associated with the workspace and environment alias.
Can I run a regular container command?
Yes. For example, `coi run -- npm test` streams output and propagates the exit status.
What does the security log contain?
Threat events in JSONL. `coi audit` streams them for your own event collection system.
Discussion
No questions or reviews yet.
Related
CLI toolsA CLI that creates separate virtual machines for coding agents, keeping their development tools away from the main host system.
Claude Code, Codex, OpenCode and pi run in a hardened container: project files only, allowlisted network, keys held by a proxy.
cli sandbox for ai agents without containers or daemons: runs Claude Code, Codex, or OpenCode with restricted access to files, network, and credentials
A guard for coding agents: blocks destructive Git and file system commands and attempts to read sensitive files before they run
A local dashboard for Claude Code, Codex CLI and OpenCode: what the agent loads, its token cost and an MCP server security scan
The safehouse command runs Claude Code, Codex and other agents in a macOS sandbox: files are closed by default and you open folders with flags
README in short
The `coi health` command checks the installation setup. The profile skill reads the schema from the CLI and uses it to validate configuration keys.