claude-code-agent-docker

<div align="center">

# Claude Code Agent Docker

### Run autonomous Claude Code agents in Docker with Telegram & Discord

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Docker](https://img.shields.io/badge/Docker-ready-2496ED?logo=docker&logoColor=white)](https://www.docker.com/)
[![Claude Code](https://img.shields.io/badge/Claude_Code-v2-6B4FBB?logo=anthropic&logoColor=white)](https://claude.ai/code)
[![Telegram](https://img.shields.io/badge/Telegram-channel-26A5E4?logo=telegram&logoColor=white)](https://core.telegram.org/bots)
[![Discord](https://img.shields.io/badge/Discord-channel-5865F2?logo=discord&logoColor=white)](https://discord.com/developers)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

**Zero-touch startup** · **Persistent state** · **Multi-agent ready** · **Fully automated**

[Quick Start](#quick-start) · [Configuration](#environment-variables) · [Multi-Agent](#multiple-agents) · [Contributing](CONTRIBUTING.md)

</div>

---

## What is this?

A production-ready Docker setup for running [Claude Code](https://claude.ai/code) agents that communicate through Telegram and Discord. Deploy one agent or a fleet — each with its own identity, channels, and workspace.

**The problem:** Claude Code is an interactive CLI tool designed for local use. Running it headlessly in a container requires bypassing onboarding wizards, configuring auth tokens, installing channel plugins, and managing state across restarts.

**This solution:** A single Docker image that handles all of that automatically. Configure via environment variables, deploy with `docker compose up -d`, and your agent is live on Telegram and Discord.

## Features

| Feature | Description |
|---------|-------------|
| **Zero-touch startup** | No interactive prompts — onboarding, trust dialogs, and permission screens all pre-configured |
| **Telegram integration** | Communicate with your agent via Telegram bot (auto-installed plugin) |
| **Discord integration** | Communicate with your agent via Discord bot (auto-installed plugin) |
| **Persistent state** | Docker volumes preserve plugins, pairings, sessions, and workspace across restarts |
| **Auto plugin install** | Telegram and Discord plugins installed automatically on first boot |
| **Multi-agent ready** | Deploy multiple agents from the same image — just change the identity file |
| **Configurable** | Agent name, model, resources — all via environment variables |
| **Secure by default** | Tokens in `.env` files with `600` permissions, `.gitignore` for secrets |

## Architecture

```
┌─────────────┐         ┌──────────────┐
│  Telegram    │         │   Discord    │
│  Bot API     │         │   Gateway    │
└──────┬──────┘         └──────┬───────┘
       │                       │
       │    ┌──────────────┐   │
       └────┤  MCP Servers ├───┘
            │  (bun)       │
            └──────┬───────┘
                   │
          ┌────────▼────────┐
          │   Claude Code   │
          │   (tmux)        │
          │                 │
          │  ┌───────────┐  │
          │  │ CLAUDE.md  │  │  ← Agent identity
          │  │ (system    │  │
          │  │  prompt)   │  │
          │  └───────────┘  │
          └────────┬────────┘
                   │
     ┌─────────────┼─────────────┐
     │             │             │
┌────▼────┐  ┌────▼────┐  ┌────▼────┐
│ .claude │  │workspace│  │  .env   │
│ volume  │  │ volume  │  │ (host)  │
└─────────┘  └─────────┘  └─────────┘
  plugins      code &       tokens &
  pairings     projects     config
  settings
```

## Quick Start

### Prerequisites

- [Docker](https://docs.docker.com/get-docker/) 20.10+
- [Docker Compose](https://docs.docker.com/compose/install/) 2.0+
- A [Claude](https://claude.ai) Pro, Max, Team, or Enterprise subscription

### 1. Clone

```bash
git clone https://github.com/naorbrig/claude-code-agent-docker.git
cd claude-code-agent-docker
```

### 2. Get a Claude Code OAuth token

On your local machine (requires Claude Code installed):

```bash
claude setup-token
```

Sign in via browser, copy the long-lived token.

### 3. Configure

```bash
cp .env.example .env
```

Edit `.env` with your OAuth token and (optionally) bot tokens:

```env
CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-your-token-here
AGENT_NAME=my-agent
AGENT_MODEL=sonnet
TELEGRAM_BOT_TOKEN=123456789:AAH...    # optional
DISCORD_BOT_TOKEN=MTIz...              # optional
```

### 4. Customize identity

Edit `CLAUDE.md` — this is your agent's system prompt. Define its personality, skills, and rules.

### 5. Deploy

```bash
docker compose up -d
```

### 6. Pair messaging channels

DM your Telegram or Discord bot. You'll receive a pairing code. Approve it:

```bash
# View the agent's screen
docker exec my-agent tmux capture-pane -t my-agent -p

# Approve Telegram pairing
docker exec my-agent tmux send-keys -t my-agent '/telegram:access pair <code>' Enter

# Approve Discord pairing
docker exec my-agent tmux send-keys -t my-agent '/discord:access pair <code>' Enter
```

Your agent is now live. Send it messages on Telegram or Discord.

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `CLAUDE_CODE_OAUTH_TOKEN` | **Yes** | — | OAuth token from `claude setup-token` |
| `AGENT_NAME` | No | `claude` | Agent display name (used for tmux session, git, and `--name`) |
| `AGENT_MODEL` | No | `sonnet` | Model: `opus`, `sonnet`, or `haiku` |
| `TELEGRAM_BOT_TOKEN` | No | — | Telegram bot token from [@BotFather](https://t.me/BotFather) |
| `DISCORD_BOT_TOKEN` | No | — | Discord bot token from [Developer Portal](https://discord.com/developers) |
| `GITHUB_TOKEN` | No | — | GitHub PAT for git operations inside the container |
| `MEMORY_LIMIT` | No | `8g` | Container memory limit |
| `CPU_LIMIT` | No | `8` | Container CPU limit |
| `MEMORY_RESERVATION` | No | `4g` | Container memory reservation |

## Multiple Agents

Deploy a fleet of agents from the same image — each with a different identity and channels.

### Option A: Separate directories

```
agents/
├── alice/
│   ├── .env          # AGENT_NAME=alice, unique tokens
│   └── CLAUDE.md     # Alice's personality
├── bob/
│   ├── .env          # AGENT_NAME=bob, unique tokens
│   └── CLAUDE.md     # Bob's personality
└── shared/
    ├── Dockerfile
    ├── entrypoint.sh
    └── docker-compose.yml
```

### Option B: Single compose file

```yaml
services:
  alice:
    build: .
    container_name: alice
    init: true
    env_file: agents/alice/.env
    volumes:
      - ./agents/alice/CLAUDE.md:/home/node/CLAUDE.md:ro
      - alice-claude:/home/node/.claude
      - alice-workspace:/home/node/workspace
    restart: unless-stopped

  bob:
    build: .
    container_name: bob
    init: true
    env_file: agents/bob/.env
    volumes:
      - ./agents/bob/CLAUDE.md:/home/node/CLAUDE.md:ro
      - bob-claude:/home/node/.claude
      - bob-workspace:/home/node/workspace
    restart: unless-stopped

volumes:
  alice-claude:
  alice-workspace:
  bob-claude:
  bob-workspace:
```

## Channel Setup

### Telegram

1. Message [@BotFather](https://t.me/BotFather) on Telegram → `/newbot`
2. Copy the bot token to your `.env` file
3. Deploy the container
4. DM your bot → receive a pairing code → approve it

### Discord

1. Create an application at [Discord Developer Portal](https://discord.com/developers/applications)
2. Go to **Bot** tab → copy the token to your `.env`
3. Enable **Privileged Gateway Intents**: Message Content, Server Members, Presence
4. Invite the bot to your server:
   ```
   https://discord.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=274877975552&integration_type=0&scope=bot+applications.commands
   ```
   > **Tip:** Your client ID is the base64-decoded first segment of the bot token.
5. DM the bot → receive a pairing code → approve it
6. Add server channels:
   ```bash
   docker exec <contain

[truncated…]