Skip to content

Commit 9cb9899

Browse files
bryant-ungbryant-ung
committed
docs: expand README with config sharing, MCP notes, and more examples
- Add detailed usage examples (one-shot commands, resume, CI mode) - Document ~/.claude folder structure (commands, agents, settings) - Add MCP support section with limitations and workarounds - Clarify OAuth two-step login process - Update docker-compose to mount ~/.claude from host - Add shell alias convenience section - Add troubleshooting for custom commands
1 parent b953f5e commit 9cb9899

2 files changed

Lines changed: 273 additions & 32 deletions

File tree

‎README.md‎

Lines changed: 246 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -17,28 +17,57 @@ docker run -it --rm \
1717
- [Docker](https://docs.docker.com/get-docker/) installed
1818
- [Anthropic API key](https://console.anthropic.com/) or Claude account for OAuth
1919

20-
## Usage
20+
## Usage Examples
2121

22-
### Using Docker Run
22+
### Basic Interactive Session
2323

2424
```bash
25-
# Basic usage with API key
25+
# Start an interactive Claude Code session
2626
docker run -it --rm \
2727
-v $(pwd):/workspace \
2828
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
2929
ungb/claude-code
30+
```
31+
32+
### One-Shot Commands
3033

31-
# With persistent config (remembers settings between runs)
34+
```bash
35+
# Ask a question about your codebase
3236
docker run -it --rm \
3337
-v $(pwd):/workspace \
34-
-v claude-config:/home/coder/.claude \
3538
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
36-
ungb/claude-code
39+
ungb/claude-code \
40+
claude "explain the architecture of this project"
3741

38-
# With git/ssh support
42+
# Generate code
3943
docker run -it --rm \
4044
-v $(pwd):/workspace \
41-
-v claude-config:/home/coder/.claude \
45+
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
46+
ungb/claude-code \
47+
claude "create a REST API endpoint for user authentication"
48+
49+
# Fix bugs
50+
docker run -it --rm \
51+
-v $(pwd):/workspace \
52+
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
53+
ungb/claude-code \
54+
claude "fix the failing tests in src/utils"
55+
56+
# Code review
57+
docker run -it --rm \
58+
-v $(pwd):/workspace \
59+
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
60+
ungb/claude-code \
61+
claude "review the changes in the last commit"
62+
```
63+
64+
### With Full Configuration (Recommended)
65+
66+
```bash
67+
# Full setup with persistent config, git, and SSH
68+
docker run -it --rm \
69+
-v $(pwd):/workspace \
70+
-v ~/.claude:/home/coder/.claude \
4271
-v ~/.ssh:/home/coder/.ssh:ro \
4372
-v ~/.gitconfig:/home/coder/.gitconfig:ro \
4473
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
@@ -47,13 +76,13 @@ docker run -it --rm \
4776

4877
### Using Docker Compose
4978

50-
1. Clone this repo or copy `docker-compose.yml` to your project:
79+
1. Copy `docker-compose.yml` to your project:
5180

5281
```bash
5382
curl -O https://raw.githubusercontent.com/ungb/claude-code-docker/main/docker-compose.yml
5483
```
5584

56-
2. Create a `.env` file with your API key:
85+
2. Create a `.env` file:
5786

5887
```bash
5988
echo "ANTHROPIC_API_KEY=your-key-here" > .env
@@ -62,70 +91,234 @@ echo "ANTHROPIC_API_KEY=your-key-here" > .env
6291
3. Run:
6392

6493
```bash
94+
# Interactive session
6595
docker compose run --rm claude
96+
97+
# One-shot command
98+
docker compose run --rm claude claude "explain this code"
6699
```
67100

68-
### Run a Specific Command
101+
### Resume a Conversation
69102

70103
```bash
71-
# Run claude with arguments
104+
# Continue from where you left off (requires persistent config)
72105
docker run -it --rm \
73106
-v $(pwd):/workspace \
107+
-v ~/.claude:/home/coder/.claude \
74108
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
75109
ungb/claude-code \
76-
claude "explain this codebase"
110+
claude --resume
111+
```
77112

78-
# Check version
79-
docker run -it --rm ungb/claude-code claude --version
113+
### Non-Interactive / CI Mode
80114

81-
# Run health check
115+
```bash
116+
# Run without prompts (for scripts/CI)
82117
docker run -it --rm \
118+
-v $(pwd):/workspace \
83119
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
84120
ungb/claude-code \
85-
claude doctor
121+
claude --yes "format all TypeScript files"
122+
```
123+
124+
## Sharing Your Claude Configuration
125+
126+
The `~/.claude` directory contains your personal Claude Code configuration including custom slash commands, skills, agents, and settings. Mount it to use your customizations inside the container.
127+
128+
### What's in ~/.claude
129+
130+
```
131+
~/.claude/
132+
├── settings.json # Global settings and preferences
133+
├── settings.local.json # Local overrides and permissions
134+
├── commands/ # Custom slash commands (.md files)
135+
│ ├── my-command.md
136+
│ └── another-command.md
137+
├── agents/ # Custom agents (.md files with YAML frontmatter)
138+
│ ├── code-reviewer.md
139+
│ └── debugger.md
140+
└── .claude.json # MCP server configurations
86141
```
87142

143+
### Mount Your Configuration
144+
145+
```bash
146+
# Share your entire .claude folder (includes commands, agents, settings)
147+
docker run -it --rm \
148+
-v $(pwd):/workspace \
149+
-v ~/.claude:/home/coder/.claude \
150+
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
151+
ungb/claude-code
152+
```
153+
154+
### Use Custom Slash Commands
155+
156+
Once your `~/.claude` is mounted, your custom commands are available:
157+
158+
```bash
159+
docker run -it --rm \
160+
-v $(pwd):/workspace \
161+
-v ~/.claude:/home/coder/.claude \
162+
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
163+
ungb/claude-code \
164+
claude "/my-custom-command"
165+
```
166+
167+
### Project-Specific Configuration
168+
169+
Projects can have their own `.claude/` directory with project-specific commands:
170+
171+
```bash
172+
# Your project's .claude/ is automatically available at /workspace/.claude/
173+
docker run -it --rm \
174+
-v $(pwd):/workspace \
175+
-v ~/.claude:/home/coder/.claude \
176+
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
177+
ungb/claude-code
178+
```
179+
180+
## MCP (Model Context Protocol) Support
181+
182+
> **Warning**: MCP support in Docker containers is limited and may require additional configuration.
183+
184+
### Current Limitations
185+
186+
MCP servers may not work out of the box in Docker because:
187+
188+
1. **Stdio-based MCP servers** need the server binary installed inside the container
189+
2. **Network-based MCP servers** need proper network configuration
190+
3. **MCP servers that access local resources** (files, databases) need those resources available in the container
191+
4. **Authentication** for MCP servers may not transfer into the container
192+
193+
### What Might Work
194+
195+
| MCP Type | Status | Notes |
196+
|----------|--------|-------|
197+
| HTTP/SSE servers (remote) | May work | Requires `--network host` or proper port mapping |
198+
| Stdio servers (local) | Unlikely | Server must be installed in container |
199+
| Servers needing local files | Partial | Files must be mounted into container |
200+
| Servers with OAuth | Unlikely | Auth flow may not complete in container |
201+
202+
### Attempting MCP with Docker
203+
204+
If you want to try MCP servers:
205+
206+
```bash
207+
# Mount MCP config and use host network
208+
docker run -it --rm \
209+
--network host \
210+
-v $(pwd):/workspace \
211+
-v ~/.claude:/home/coder/.claude \
212+
-v ~/.claude.json:/home/coder/.claude.json:ro \
213+
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
214+
ungb/claude-code
215+
```
216+
217+
### Building a Custom Image with MCP Servers
218+
219+
For stdio-based MCP servers, you'll need to build a custom image:
220+
221+
```dockerfile
222+
FROM ungb/claude-code:latest
223+
224+
# Switch to root to install packages
225+
USER root
226+
227+
# Example: Install an MCP server
228+
RUN npm install -g @anthropic/mcp-server-example
229+
230+
# Switch back to coder user
231+
USER coder
232+
```
233+
234+
### MCP Investigation Needed
235+
236+
Full MCP support in Docker containers requires further investigation:
237+
- Testing specific MCP servers for compatibility
238+
- Network configuration for different MCP transport types
239+
- Credential/auth forwarding for authenticated MCP servers
240+
- Potential need for Docker-in-Docker for some servers
241+
242+
If you have insights or solutions for MCP in Docker, please open an issue or PR!
243+
88244
## Authentication
89245

90246
### Option 1: API Key (Recommended for Docker)
91247

92-
Get an API key from [Anthropic Console](https://console.anthropic.com/) and pass it as an environment variable:
248+
Get an API key from [Anthropic Console](https://console.anthropic.com/):
93249

94250
```bash
95251
-e ANTHROPIC_API_KEY=sk-ant-...
96252
```
97253

98254
### Option 2: OAuth Login
99255

100-
For browser-based OAuth (requires host network):
256+
OAuth login is a two-step process:
257+
258+
**Step 1: Login (once)**
101259

102260
```bash
261+
# Login with browser-based OAuth (requires host network for callback)
103262
docker run -it --rm \
104263
--network host \
105-
-v $(pwd):/workspace \
106-
-v claude-config:/home/coder/.claude \
264+
-v ~/.claude:/home/coder/.claude \
107265
ungb/claude-code \
108266
claude login
109267
```
110268

269+
This opens a browser, authenticates, and saves tokens to `~/.claude/`.
270+
271+
**Step 2: Use normally**
272+
273+
```bash
274+
# Now run without API key - tokens are in ~/.claude
275+
docker run -it --rm \
276+
-v $(pwd):/workspace \
277+
-v ~/.claude:/home/coder/.claude \
278+
ungb/claude-code
279+
```
280+
281+
> **Note**: Mount `~/.claude` from your host so tokens persist between container runs.
282+
111283
## Volume Mounts
112284

113285
| Mount | Purpose |
114286
|-------|---------|
115287
| `/workspace` | Your project directory (required) |
116-
| `/home/coder/.claude` | Claude config and cache (optional, for persistence) |
117-
| `/home/coder/.ssh` | SSH keys for git operations (optional, read-only) |
118-
| `/home/coder/.gitconfig` | Git configuration (optional, read-only) |
288+
| `/home/coder/.claude` | Claude config, commands, agents, settings |
289+
| `/home/coder/.ssh` | SSH keys for git operations (read-only) |
290+
| `/home/coder/.gitconfig` | Git configuration (read-only) |
291+
| `/home/coder/.claude.json` | MCP server configurations (read-only) |
119292

120293
## Environment Variables
121294

122295
| Variable | Required | Description |
123296
|----------|----------|-------------|
124297
| `ANTHROPIC_API_KEY` | Yes* | Your Anthropic API key |
125298
| `ANTHROPIC_API_BASE_URL` | No | Custom API endpoint (for proxies) |
299+
| `CLAUDE_CONFIG_DIR` | No | Override config directory location |
126300

127301
*Required unless using OAuth login
128302

303+
## Utility Commands
304+
305+
```bash
306+
# Check version
307+
docker run --rm ungb/claude-code claude --version
308+
309+
# Run health check
310+
docker run --rm \
311+
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
312+
ungb/claude-code \
313+
claude doctor
314+
315+
# List available commands
316+
docker run --rm \
317+
-v ~/.claude:/home/coder/.claude \
318+
ungb/claude-code \
319+
claude /help
320+
```
321+
129322
## Building Locally
130323

131324
```bash
@@ -162,6 +355,18 @@ docker run -it --rm \
162355
ungb/claude-code
163356
```
164357

358+
### Custom Commands Not Found
359+
360+
Make sure you're mounting your `~/.claude` directory:
361+
362+
```bash
363+
docker run -it --rm \
364+
-v $(pwd):/workspace \
365+
-v ~/.claude:/home/coder/.claude \
366+
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
367+
ungb/claude-code
368+
```
369+
165370
### OAuth Login Not Working
166371

167372
Use `--network host` to allow the OAuth callback:
@@ -170,11 +375,27 @@ Use `--network host` to allow the OAuth callback:
170375
docker run -it --rm \
171376
--network host \
172377
-v $(pwd):/workspace \
173-
-v claude-config:/home/coder/.claude \
378+
-v ~/.claude:/home/coder/.claude \
174379
ungb/claude-code \
175380
claude login
176381
```
177382

383+
## Shell Alias (Convenience)
384+
385+
Add to your `~/.bashrc` or `~/.zshrc`:
386+
387+
```bash
388+
alias claude-docker='docker run -it --rm \
389+
-v $(pwd):/workspace \
390+
-v ~/.claude:/home/coder/.claude \
391+
-v ~/.ssh:/home/coder/.ssh:ro \
392+
-v ~/.gitconfig:/home/coder/.gitconfig:ro \
393+
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
394+
ungb/claude-code claude'
395+
396+
# Usage: claude-docker "explain this code"
397+
```
398+
178399
## License
179400

180401
MIT License - see [LICENSE](LICENSE)

0 commit comments

Comments
 (0)