cli-agent container

A minimal convention for running cli agents inside Docker containers. It limits host access and lets agents install and manage dependencies in an isolated environment.

What it does

• Isolates agents with minimal mounts
• Bootstraps per project once (installs required tools inside the container)
• Works consistently across developers and CI/CD
• Reuses a persistent per‑project container for quick startup

How it works

• Each agent provides a small base image that installs the cli and sets defaults
• A project opts in by adding exactly one file: <name>.<agent-type> (for example: deno.cursor-agent)
  • This bash script runs once on first use to bootstrap the environment inside the container
• A lightweight shell function (per agent):
  • Creates or resumes a container named <name>-<agent-type>
  • Mounts the project workspace
  • Runs the bootstrap script once, then executes the agent cli inside the container as your user

Example

• See cursor-agent/ for a reference implementation and usage
• Add a script like my-app.cursor-agent in your project root to declare dependencies and setup

Status: this repo currently includes a proof‑of‑concept for cursor-agent to demonstrate the workflow. Additional agents can follow the same pattern.

Why use this

• Security and minimalism
• Reproducibility
• Simplicity (bash + Docker)

For details on the cursor agent, see cursor-agent/README.md.