aishell

# aishell

Docker sandbox for running AI coding agents (Claude Code, OpenCode, Codex CLI, Gemini CLI, Pi) in ephemeral containers, with optional development tools (OpenSpec).

## Why Docker?

AI coding agents run arbitrary code — installing packages, writing scripts, deleting files — with
minimal human review. On your host machine, one bad command can reach your SSH keys, cloud
credentials, browser data, and every file you own.

Docker draws a boundary. The agent sees only what you mount: your project directory and its config
files. It cannot touch `~/.ssh`, overwrite your shell config, or install packages that outlive the
session. When the agent exits, the container disappears. Nothing accumulates.

A fixed base image also means every developer runs agents in the same environment — no "works on my
machine" failures. And if you run multiple agents simultaneously, each gets its own container with no
shared state.

## Why aishell?

Running AI coding agents in Docker means dealing with:

```bash
docker run -it --rm \
  -v "$PWD:$PWD" \
  -v "$HOME/.gemini:/home/dev/.gemini" \
  -v "$HOME/.config/claude-code:/home/dev/.config/claude-code" \
  -w "$PWD" \
  -e ANTHROPIC_API_KEY \
  --name gemini-session \
  my-gemini-image gemini
```

And that's the simple version. You still need to:

- **Get paths right** - AI agents reference absolute paths. If `/home/you/project` on your host becomes `/app` in the container, file references break.
- **Preserve git identity** - Without setup, commits appear as "root" or "unknown". You need to pass through `.gitconfig` or set `GIT_AUTHOR_*` variables.
- **Reproduce across machines** - That 200-character docker command you perfected? Good luck remembering it on your laptop.

aishell handles all of this. One command, consistent behavior, works everywhere.

### Why not devcontainers?

Devcontainers solve a different problem. They create persistent development environments tied to your IDE.

aishell is purpose-built for AI agents:

- **Ephe