aerovato/container

container – Isolated workspaces for AI coding agents

What it is

• container is a CLI tool that creates a per‑project Docker (or Podman) environment. Each AI‑driven coding agent gets its own persistent, isolated workspace so it can install packages, run tools, and modify the filesystem without touching the host system or other projects.

Why it matters

• AI agents (e.g., OpenCode, Code‑LLMs) often need to run commands, compile code, or install dependencies. Doing this directly on the host can lead to version conflicts, polluted environments, or accidental destructive actions. By sandboxing each project in a container, the tool makes “hands‑off” agent workflows safer and more reproducible.

How to get it

• macOS / Linux – run the install script:

  curl -fsSL https://container.aerovato.com/install.sh | sh
  

• Windows PowerShell – run the PowerShell installer:

  irm https://container.aerovato.com/install.ps1 | iex
  

• npm – a global package is also published:

  npm install -g @aerovato/container
  

First‑time setup

1. Run container init and follow the guided onboarding to pick a base image, development tools, runtime (Docker/Podman), and any host‑directory mounts you want.
2. The tool builds a shared base image that will be reused for all projects.

Typical workflow

cd /path/to/your/project
container            # launches the project's workspace
# Inside the container you can use your usual agent commands
opencode            # start the AI coding agent
npm install <pkg>   # or any other tool you need

The project is mounted at /root/<project‑name> inside the container and the state persists across runs.

Agent integration

• A portable Container skill (skills/container/SKILL.md) can be installed on the host so an AI agent can issue commands like container build user or container run … without manual typing.
• Installation example:

  npx skills add aerovato/container --skill container   # project‑scoped
  npx skills add aerovato/container --skill container --global   # all projects
  

Key commands

Command	What it does
container	Open the current project's workspace
container run <path>	Open a specific project
container list	Show all managed containers
container stop / container remove	Stop or delete a workspace
`container build [tools	harness
container settings	Edit the JSON configuration (~/.code-container/settings.json)

Customization

• Add extra Debian/apt packages or custom setup commands in ~/.code-container/Dockerfile.User and rebuild with container build user.
• Adjust harnesses, tools, runtime flags, and mount points via the JSON settings file.

Security notes

• The container isolates the host, but the project directory is mounted read‑write, so a malicious or mis‑behaving agent could still delete or alter files.
• Network access is retained inside the container, and container does not protect against prompt‑injection or agent misalignment. Keep critical data under version control and only expose the resources the agent truly needs.

Built with Operator Memory

• The repo uses Aerovato’s Operator Memory system for durable, agent‑maintained documentation. The shared “brain” lives in .operator‑shared/ and can be accessed by installing @aerovato/operator-helper.

License

• BSD‑3‑Clause (see LICENSE.md).