/cli-agent-container

cli-agent-container is a simple convention for wrapping CLI agents in containers. Each project adds a single <name>.<agent-type> script to bootstrap dependencies once; a tiny shell helper then creates/resumes a persistent per‑project container and runs the agent inside it.

Primary LanguageDockerfileApache License 2.0Apache-2.0

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.