aienv - Secure Sandboxes for AI Coding Agents

Features

🐳

Isolated Docker Sandboxes

Agents run in containers, not your host. Complete filesystem isolation with zero host pollution.

🌐

Network Enforcement

Whitelist APIs with allow/deny/learn modes. Learn mode suggests an allowlist for new environments.

📝

Complete Audit Trails

JSONL logs of all commands and network calls. Full session traceability for compliance and debugging.

🎨

Black-box Agent Design

Works with OpenCode, Claude Code, Cursor, Pi, or any CLI agent. Zero code changes needed.

🗂️

Permission Control

Mount selectively and run read-only by default. Declare exactly what the agent can see and modify.

🚀

Session Isolation

Each aienv up is a fresh, independent container. No state leaks between sessions.

Quick Start

Install aienv

Install the CLI tool using Go:

bash

$ go install github.com/kapilratnani/aienv@latest

Create an Environment

Run the interactive creation wizard:

bash

$ aienv create claude-dev

Launch the Sandbox

Builds the image if needed and starts the sandbox:

bash

$ aienv up claude-dev

Send a Prompt (Optional)

Launch and send a prompt directly in one-shot mode:

bash

$ aienv up claude-dev -p "Refactor the auth module to use JWT and create the PR using gh cli" -x

Recipes

Ready-to-use environment configurations for popular AI coding agents.

🌻 Start Simple

yaml

env:
  name: my-coding-env
  description: coding env for my project

agent:
  install:
    - npm install -g opencode-ai
  command:
    - opencode
  env:
    - GITHUB_TOKEN: "env:GITHUB_TOKEN"
  mounts:
    - source: /path/to/your/project
      target: /workspace
      writable: true

🔧 Claude Code

yaml

env:
  name: claude-dev
  description: Sandboxed Claude Code

agent:
  install:
    - npm install -g @anthropic-ai/claude-code
  command: [claude]
  env:
    ANTHROPIC_API_KEY: "env:ANTHROPIC_API_KEY"
  mounts:
    - source: /home/you/projects/my-app
      target: /workspace
      writable: true
    - source: ~/.claude
      target: ~/.claude
      writable: true

🎯 OpenCode

yaml

env:
  name: opencode-dev
  description: Develop with OpenCode

agent:
  install:
    - npm install -g opencode-ai
  command: [opencode]
  prompt_flag: "--prompt"
  exit_subcommand: "run"
  args: [--model, opencode/deepseek-v4-flash-free]
  mounts:
    - source: /home/you/projects/aienv
      target: /workspace
      writable: true

🤖 Pi

yaml

env:
  name: pi-dev
  description: Sandboxed Pi coding agent

agent:
  install:
    - npm install -g @earendil-works/pi-coding-agent
  command: [pi]
  env:
    ANTHROPIC_API_KEY: "env:ANTHROPIC_API_KEY"
  mounts:
    - source: /home/you/projects/my-app
      target: /workspace
      writable: true

🎨 Bring Your Own

yaml

# Any CLI-based agent works — just change agent.install and agent.command
env:
  name: my-agent
  description: My custom AI agent

agent:
  install:
    - npm install -g my-agent-cli
  command: [my-agent]
  mounts:
    - source: /home/you/projects/my-app
      target: /workspace
      writable: true