DEV Community

Cover image for aienv - Sandbox any agent
Kapil Ratnani
Kapil Ratnani

Posted on

aienv - Sandbox any agent

#ai #security #sandbox #agents

AI coding agents are amazing — until they rm -rf something, leak an API key, or leave your project in a broken state.

Every project needs different tools, credentials, and configs. Yet most of us run agents directly on our host, giving them unrestricted filesystem access, unfiltered network calls, and no audit trail.

aienv fixes that.

github.com/kapilratnani/aienv

How It Works

One YAML file defines everything your agent needs: the binary to run, which files to mount, what APIs it can talk to, and which environment variables to inject. aienv builds a Docker image from that YAML, launches a sandboxed container, runs an HTTP proxy for network enforcement, and writes every network request to a JSONL audit log.

Agents are treated as black boxes — aienv doesn't care whether you run Claude Code, OpenCode, Cursor, Pi, or a custom script. If it runs on a CLI, it works.

Quick Start

Install:

go install github.com/kapilratnani/aienv@latest
Enter fullscreen mode Exit fullscreen mode

Create an environment:

aienv create my-coding-env
Enter fullscreen mode Exit fullscreen mode

This walks you through an interactive setup. The result is a YAML file at ~/.local/share/aienv/my-coding-env/env.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
Enter fullscreen mode Exit fullscreen mode

Launch the sandbox:

aienv up my-coding-env
Enter fullscreen mode Exit fullscreen mode

Your agent runs inside an isolated Docker container. Your host filesystem is untouched. When you exit, the container is removed.

Mount Agent Configs & Skills

Agents need their configs, context files, and skill directories. Mount them as read-only by default — only make writable what the agent must modify.

agent:
  mounts:
    - source: ~/projects/my-app
      target: /workspace
      writable: true
    - source: ~/.claude
      target: ~/.claude
      writable: true
    - source: ~/.agents/skills/caveman
      target: ~/.agents/skills/caveman
    - source: ~/.agents/skills/agent-browser
      target: ~/.agents/skills/agent-browser
Enter fullscreen mode Exit fullscreen mode

All mounts are read-only by default. The writable: true flag is explicit — you opt into it.

Environment Variables

Pass secrets through environment variables from the host — never baked into images:

agent:
  env:
    ANTHROPIC_API_KEY: "env:ANTHROPIC_API_KEY"
    GITHUB_TOKEN: "env:GITHUB_TOKEN"
Enter fullscreen mode Exit fullscreen mode

The env: prefix tells aienv to passthrough the value from your host environment at runtime. The image stays portable and hash-cached.

Dependencies

Need system packages or custom installs? Declare them:

deps:
  packages: [nodejs, git, curl, golang-go, ripgrep]
  custom:
    - go install github.com/foo/bar@latest
    - cargo install some-tool
Enter fullscreen mode Exit fullscreen mode

aienv installs these at build time. The image is cached by the SHA-256 hash of your entire YAML — change anything, and the image auto-rebuilds on next activation.

One-Shot Mode — Tell the Agent What to Do and Walk Away

This is where aienv shines.

Instead of dropping into an interactive session, you can send a prompt directly and let the agent work independently. The agent does its job, commits changes, creates a PR, and exits. The container self-destructs. You get a clean audit log.

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

The -p flag sends the prompt. The -x flag means one-shot mode — no TUI, no waiting. The agent starts, executes, and exits.

This is perfect for CI/CD, scheduled tasks, or delegating work you don't want to supervise. Combine it with git worktrees (below) for full isolation, and the agent has zero side effects on your host's working tree.

Network Permissions

By default, the agent has unfiltered network access. Define an allowlist and everything else is blocked:

permissions:
  network:
    allow:
      - api.anthropic.com
      - api.github.com
      - raw.githubusercontent.com
    deny:
      - "*"
Enter fullscreen mode Exit fullscreen mode

The proxy runs on the host as a Go HTTP/HTTPS proxy. The container is pointed at it via HTTP_PROXY/HTTPS_PROXY. Every request is checked against the allowlist.

Learn Mode

No network rules configured? The proxy runs in learn mode — it records every hostname the agent contacts and prints a suggested allowlist when the session ends:

Suggested permissions.network.allow for "claude-dev":
  - api.anthropic.com
  - raw.githubusercontent.com
  - api.github.com
Enter fullscreen mode Exit fullscreen mode

Add them to your YAML and you're locked down.

Git Worktree Isolation

For serious isolation, use --worktree / -w:

aienv up my-env -w feature/jwt-auth
Enter fullscreen mode Exit fullscreen mode

This creates a git worktree — a linked checkout that shares the repo's .git directory — mounts it into the sandbox as the agent's workspace, and cleans it up when the session ends. Your main working tree stays pristine, and multiple agents can work on different branches simultaneously without interference.

Audit Trails

Every session produces a JSONL audit log at ~/.local/share/aienv/<name>/audit/<session-id>/:

session.meta.json    — env name, agent command, start time
network.jsonl        — every HTTP request and HTTPS CONNECT
Enter fullscreen mode Exit fullscreen mode

Each activation gets a unique session ID. Concurrent activations are fully independent. The audit dir is mounted into the container so in-agent scripts can write cost-extraction data.

Full Example: Claude Code with Permissions, Worktree, and One-Shot

Here's a complete environment for automated refactoring with Claude Code:

env:
  name: claude-dev
  description: Sandboxed Claude Code for my project

agent:
  install:
    - npm install -g @anthropic-ai/claude-code
  command: [claude]
  env:
    ANTHROPIC_API_KEY: "env:ANTHROPIC_API_KEY"
    GITHUB_TOKEN: "env:GITHUB_TOKEN"
  mounts:
    - source: ~/.claude
      target: ~/.claude
      writable: true
    - source: ~/.config/gh
      target: ~/.config/gh
      writable: true

deps:
  packages: [nodejs, git, gh]

permissions:
  network:
    allow:
      - api.anthropic.com
      - api.github.com
      - raw.githubusercontent.com
    deny:
      - "*"

audit:
  persist: true
  capture: [network]
Enter fullscreen mode Exit fullscreen mode

Launch it:

# Interactive session
aienv up claude-dev

# One-shot: refactor and create PR, fully isolated in a worktree
aienv up claude-dev -w feature/jwt-auth -p "Refactor the auth module to use JWT and create the PR using gh cli" -x
Enter fullscreen mode Exit fullscreen mode

The agent:

  1. Starts in a dedicated git worktree on feature/jwt-auth
  2. Can only reach Anthropic and GitHub APIs
  3. Has GITHUB_TOKEN and ANTHROPIC_API_KEY injected at runtime
  4. Refactors the auth module, commits, pushes, creates a PR
  5. Exits. Container removed. Audit logged. Worktree cleaned.

No host contamination. No manual cleanup. Full traceability.

Beyond the Basics

  • Trust prompts — First activation shows mounts + network rules and asks for confirmation. Cached by YAML hash, re-prompted on config change.
  • Debug shell — aienv shell <name> drops you into /bin/bash inside the sandbox without the agent.
  • Cleanup — aienv clean removes orphaned Docker images, audit dirs, and trust cache entries.
  • Black-box design — Any CLI agent works. Just change agent.install and agent.command in YAML. Zero code changes.
  • XDG-compliant — Config at ~/.local/share/aienv/, trust cache at ~/.config/aienv/trust/.

Try It 

go install github.com/kapilratnani/aienv@latest
aienv create my-env
aienv up my-env
Enter fullscreen mode Exit fullscreen mode

The project is MIT licensed, contributions are welcome, and the architecture decision records are open for discussion.

Star the repo at github.com/kapilratnani/aienv, open an issue if something breaks, and let us know what agents you're running in sandboxes.

The future of AI coding is isolated, auditable, and reproducible. aienv is a step in that direction.

This article was written with an AI agent running inside an aienv sandbox. Of course.

Top comments (0)