docker-claude-code

# 🧠 docker-claude-code

[Claude Code](https://claude.com/product/claude-code) in a Docker container. No host installs. No permission nightmares. Just vibes and `--dangerously-skip-permissions`.

Four ways to unleash it:

- **Interactive** — drop-in `claude` CLI replacement, persistent container, picks up where you left off
- **Programmatic** — pass a prompt, get a response, pipe it into your cursed pipeline
- **API server** — HTTP endpoints for prompts, file management, monitoring. Slap it in your infra
- **Telegram bot** — talk to Claude from your phone when you're takin' a shit. Per-chat workspaces, models, effort levels, file sharing, shell access

## Table of Contents

- [Why?](#-why)
- [Image Variants](#-image-variants)
- [What's Inside?](#-whats-inside-full-image)
- [Requirements](#-requirements)
- [Quick Start](#%EF%B8%8F-quick-start)
- [ENV Vars](#-env-vars)
- [Usage](#-usage)
  - [Interactive mode](#interactive-mode)
  - [Programmatic mode](#programmatic-mode)
  - [API mode](#api-mode)
  - [Telegram mode](#telegram-mode)
- [Customization](#-customization)
- [Gotchas](#-gotchas)
- [License](#-license)

## 💀 Why?

Because installing things natively is for people who enjoy suffering.

This image exists so you can run Claude Code in a fully isolated container with every tool known to humankind pre-installed, passwordless sudo, docker-in-docker, and zero concern for your host system's wellbeing. It's like giving an AI a padded room with power tools.

## 🎞️ Image Variants

Pick your poison:

### `latest` (full) — the kitchen sink

Everything pre-installed. Go, Python, Node, C/C++, Terraform, kubectl, database clients, linters, formatters, the works. Big image, zero wait time. Claude wakes up and gets to work immediately.

```bash
curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-claude-code/master/install.sh | bash
```

### `latest-minimal` — diet mode

Just enough to run Claude: Ubuntu, git, curl, Node.js, Docker. Claude has passwordless sudo so it'll install whatever it needs on the fly. Smaller pull, but first run takes longer while Claude figures out its life choices.

```bash
CLAUDE_MINIMAL=1 curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-claude-code/master/install.sh | bash
```

Pro tip: use `~/.claude/init.d/*.sh` hooks to pre-install your tools on first container create instead of waiting for Claude to `apt-get` its way through life.

### Side by side

|                                       | `latest` (full) | `latest-minimal` |
| ------------------------------------- | :-------------: | :--------------: |
| Ubuntu 22.04                          |       yes       |       yes        |
| git, curl, wget, jq                   |       yes       |       yes        |
| Node.js LTS + npm                     |       yes       |       yes        |
| Docker CE + Compose                   |       yes       |       yes        |
| Claude Code CLI                       |       yes       |       yes        |
| Go 1.26.1 + tools                     |       yes       |        -         |
| Python 3.12.11 + tools                |       yes       |        -         |
| Node.js dev tools                     |       yes       |        -         |
| C/C++ tools                           |       yes       |        -         |
| DevOps (terraform, kubectl, helm, gh) |       yes       |        -         |
| Database clients                      |       yes       |        -         |
| Shell utilities (ripgrep, bat, etc.)  |       yes       |        -         |

## 🎞️ What's Inside? (full image)

The full image is a buffet of dev tools. Here's what Claude gets to play with:

**Languages & runtimes:**

- Go 1.26.1 with the whole toolchain (golangci-lint, gopls, delve, staticcheck, gofumpt, gotests, impl, gomodifytags)
- Python 3.12.11 via pyenv with linters, formatters, testing (flake8, black, isort, autoflake, pyright, mypy, vulture, pytest, poetry, pipenv) plus common libs (requests, beautifulsoup4, lxml, pyyaml, toml)
- Node.js LTS with the npm ecosystem loaded (eslint, prettier, typescript, ts-node, yarn, pnpm, nodemon, pm2, framework CLIs, newman, http-server, serve, lighthouse, storybook)
- C/C++ (gcc, g++, make, cmake, clang-format, valgrind, gdb, strace, ltrace)

**DevOps & infra:**

- Docker CE with Docker Compose (docker-in-docker chaos)
- Terraform, kubectl, helm, gh CLI

**Databases:**

- sqlite3, postgresql-client, mysql-client, redis-tools

**Shell & system:**

- jq, tree, ripgrep, bat, exa, fd-find, ag, htop, tmux, shellcheck, shfmt, httpie, vim, nano
- Archive tools (zip, unzip, tar), networking (net-tools, iputils-ping, dnsutils)

**Magic under the hood:**

- Auto-generated `CLAUDE.md` in workspace listing all available tools (so Claude knows what it has)
- Auto-Git config from env vars
- Auto-updates on interactive startup (skip with `--no-update`), background auto-updater disabled
- Workspace trust dialog pre-accepted (no annoying prompts)
- Custom scripts via `~/.claude/bin` (in PATH automatically)
- Init hooks via `~/.claude/init.d/*.sh` (run once on first container create)
- Session continuity with `--continue` / `--no-continue` / `--resume <session_id>`
- Debug logging (`DEBUG=true`) with timestamps everywhere

## 📋 Requirements

- Docker installed and running. That's it.

## ⚙️ Quick Start

### One-liner install

```bash
# full image (recommended)
curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-claude-code/master/install.sh | bash

# minimal image
CLAUDE_MINIMAL=1 curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-claude-code/master/install.sh | bash

# custom binary name (if you already have a native `claude` install)
curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-claude-code/master/install.sh | bash -s -- dclaude
# or: CLAUDE_BIN_NAME=dclaude curl -fsSL .../install.sh | bash
```

### Manual setup

If you don't trust piping scripts to bash (understandable):

```bash
# 1. create dirs
mkdir -p ~/.claude
mkdir -p "$HOME/.ssh/claude-code"

# 2. generate SSH keys (for git push/pull inside the container)
ssh-keygen -t ed25519 -C "claude@claude.ai" -f "$HOME/.ssh/claude-code/id_ed25519" -N ""
# then add the pubkey to GitHub/GitLab/wherever

# 3. pull
docker pull psyb0t/claude-code:latest
# or: docker pull psyb0t/claude-code:latest-minimal

# 4. check install.sh for how the wrapper script works and wire it up yourself
```

## 🔐 ENV Vars

### Wrapper script vars

Set these on your host (e.g. `~/.bashrc`). The wrapper forwards them to the container.

| Variable                  | What it does                                                                   | Default              |
| ------------------------- | ------------------------------------------------------------------------------ | -------------------- |
| `CLAUDE_GIT_NAME`         | Git commit name inside the container                                           | _(none)_             |
| `CLAUDE_GIT_EMAIL`        | Git commit email inside the container                                          | _(none)_             |
| `ANTHROPIC_API_KEY`       | API key for authentication                                                     | _(none)_             |
| `CLAUDE_CODE_OAUTH_TOKEN` | OAuth token for authentication                                                 | _(none)_             |
| `CLAUDE_DATA_DIR`         | Custom `.claude` data directory                                                | `~/.claude`          |
| `CLAUDE_SSH_DIR`          | Custom SSH key directory                                                       | `~/.ssh/claude-code` |
| `CLAUDE_INSTALL_DIR`      | Custom install path for the wrapper (install-time only)                        | `/usr/local/bin`     |
| `CLAUDE_BIN_NAME`         | Custom binary name (install-time only)                                         | `claude`             |
| `CLAUDE_ENV_*`            | Forward custom env vars (prefix is stripped: `CLAUDE_ENV_FOO=bar` → `FOO=bar`) | _(none)_          

[truncated…]