chenxizhang/claude-agent-web

By chenxizhang

•Updated 8 months ago

Web-based AI assistant powered by Claude Agent SDK with full Claude Code capabilities

Image

Machine learning & AI

Web servers

1.6K

Overview Tags

chenxizhang/claude-agent-web repository overview

⁠Claude Agent Web

A web-based AI assistant powered by Claude Agent SDK⁠, providing a chat interface with full access to Claude Code's capabilities including file operations, code execution, and web search.

⁠Quick Start with Docker

Pull and run the pre-built Docker image from Docker Hub⁠.

⁠Minimal Setup

docker run -d -p 3000:3000 \
  -e ANTHROPIC_API_KEY="your-api-key" \
  chenxizhang/claude-agent-web

Then open http://localhost:3000⁠ in your browser.

⁠Using an Environment File (Recommended)

For production or multi-option setups, create a .env.docker file to keep configuration organized and secrets out of your shell history.

1. Create .env.docker:

# API Configuration
ANTHROPIC_API_KEY=your-api-key
ANTHROPIC_BASE_URL=https://your-proxy-or-azure-endpoint.com/anthropic
CLAUDE_MODEL=claude-sonnet-4-5

# Agent Configuration (optional)
AGENT_INSTRUCTIONS_FILE=/plugins/my-agent/instructions.md
AGENT_PLUGINS=/plugins/my-agent

# UI (optional)
APP_TITLE=My AI Assistant

# Authentication (optional — omit this section to disable auth)
AUTH_ENABLED=true
AUTH_TRUST_HOST=true
AUTH_URL=http://localhost:3000
AUTH_SECRET=your-random-secret-base64

# Restrict login to specific email domains (optional)
AUTH_ALLOWED_PATTERN=email:.*@yourcompany\.com$

# Microsoft Entra ID (optional)
AUTH_MICROSOFT_ENTRA_ID_ID=your-client-id
AUTH_MICROSOFT_ENTRA_ID_SECRET=your-client-secret
AUTH_MICROSOFT_ENTRA_ID_ISSUER=https://login.microsoftonline.com/common/v2.0

# GitHub OAuth (optional)
AUTH_GITHUB_ID=your-github-client-id
AUTH_GITHUB_SECRET=your-github-client-secret

# Google OAuth (optional)
AUTH_GOOGLE_ID=your-google-client-id
AUTH_GOOGLE_SECRET=your-google-client-secret

2. Run the container:

docker run -d --name claude-agent-web -p 3000:3000 \
  --env-file .env.docker \
  chenxizhang/claude-agent-web

⁠Running with Plugins

Claude Agent Web supports Claude Code plugins⁠. Mount your plugin directory into the container and configure it via environment variables.

Plugin directory structure (example):

my-agent/
├── .claude-plugin/
│   └── plugin.json          # Plugin manifest
├── instructions.md           # Agent instructions (role, rules, tools)
├── skills/                   # Skill definitions
├── commands/                 # Slash commands
└── scenarios/                # Reference data loaded on-demand

Run with a plugin:

docker run -d --name claude-agent-web -p 3000:3000 \
  --env-file .env.docker \
  -v /path/to/my-agent:/plugins/my-agent \
  chenxizhang/claude-agent-web

The key environment variables in .env.docker for plugin support:

# Point to the instructions file inside the mounted plugin
AGENT_INSTRUCTIONS_FILE=/plugins/my-agent/instructions.md

# Register the plugin (semicolon-separated for multiple plugins)
AGENT_PLUGINS=/plugins/my-agent

Multiple plugins:

docker run -d --name claude-agent-web -p 3000:3000 \
  --env-file .env.docker \
  -v /path/to/plugin-a:/plugins/plugin-a \
  -v /path/to/plugin-b:/plugins/plugin-b \
  chenxizhang/claude-agent-web

With .env.docker containing:

AGENT_PLUGINS=/plugins/plugin-a;/plugins/plugin-b

⁠Features

Full Claude Code Integration: Access to all built-in Claude Code tools (Read, Write, Edit, Bash, Glob, Grep, WebSearch, etc.)
Sandboxed Execution: Agent operates in an isolated workspace directory for security
Streaming Responses: Real-time streaming of AI responses with SSE (Server-Sent Events)
Session Management: Supports conversation resumption via session IDs
Plugin Support: Load custom Claude Code plugins at runtime
Flexible Model Selection: Choose between Haiku (fast), Sonnet (balanced), or Opus (powerful)
Interactive Q&A: Supports Claude's AskUserQuestion tool for interactive conversations

⁠Environment Variables

Variable	Required	Default	Description
`ANTHROPIC_API_KEY`	Yes	-	Anthropic API key for authentication
`ANTHROPIC_BASE_URL`	No	`https://api.anthropic.com`	Custom API endpoint (for proxies or Azure)
`CLAUDE_MODEL`	No	`claude-haiku-4-5`	Default model (`claude-haiku-4-5`, `claude-sonnet-4-5`, `claude-opus-4-5`)
`AGENT_WORKSPACE`	No	`/agentspace`	Working directory for the agent (sandboxed)
`AGENT_INSTRUCTIONS`	No	-	Custom agent instructions (inline text)
`AGENT_INSTRUCTIONS_FILE`	No	-	Path to agent instructions file (takes priority over `AGENT_INSTRUCTIONS`)
`AGENT_PLUGINS`	No	-	Semicolon-separated plugin directory paths
`APP_TITLE`	No	`Lumen`	App title displayed in header
`AUTH_ENABLED`	No	`false`	Enable OAuth authentication
`AUTH_URL`	No	-	Public URL of the app (required for OAuth callbacks in Docker)
`AUTH_SECRET`	No	-	NextAuth secret (required when auth is enabled)
`AUTH_ALLOWED_PATTERN`	No	-	Regex to restrict login (matched against `email:xxx\|name:xxx\|id:xxx`)

⁠API Reference

⁠POST /api/chat

Send a message to the AI assistant.

Request Body:

{
  // Required: The user's message
  prompt: string;

  // Optional: Session ID for conversation continuity
  sessionId?: string;

  // Optional: Plugin directories to load
  plugins?: string[];

  // Optional: Model selection
  // - 'claude-haiku-4-5' (fastest, default)
  // - 'claude-sonnet-4-5' (balanced)
  // - 'claude-opus-4-5' (most capable)
  model?: string;

  // Optional: Specific tools to load
  // If not specified, all Claude Code tools are loaded
  tools?: string[];

  // Optional: Maximum conversation turns
  maxTurns?: number;
}

Response: Server-Sent Events (SSE) stream

Event Types:

Event Type	Description	Payload
`init`	Session initialized	`{ sessionId: string }`
`text`	Streaming text content	`{ content: string }`
`tool_use`	Tool invocation	`{ toolName: string, toolInput: object }`
`question`	Interactive question	`{ question: { id, questions: [...] } }`
`done`	Completion	`{ result: string, sessionId: string }`
`error`	Error occurred	`{ error: string }`

Example:

curl -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"prompt": "List files in the current directory"}'

⁠Available Tools

When tools is not specified, all Claude Code built-in tools are available:

Category	Tools
File Operations	`Read`, `Write`, `Edit`, `Glob`, `Grep`
Code Execution	`Bash`
Web	`WebSearch`, `WebFetch`
User Interaction	`AskUserQuestion`
Task Management	`Task`, `TaskCreate`, `TaskUpdate`, `TaskList`, `TaskGet`
Planning	`EnterPlanMode`, `ExitPlanMode`
Notebook	`NotebookEdit`

To load only specific tools for faster performance:

{
  "prompt": "Read the config file",
  "tools": ["Read", "Glob"]
}

⁠Model Comparison

Model	Speed	Capability	Use Case
`claude-haiku-4-5`	Fastest	Good	Simple tasks, quick responses
`claude-sonnet-4-5`	Medium	Better	General purpose, balanced
`claude-opus-4-5`	Slowest	Best	Complex reasoning, analysis

⁠Security

Sandboxed Execution: All file operations are restricted to /agentspace
Non-root Container: Runs as unprivileged nextjs user
Permission Bypass: Uses bypassPermissions mode - ensure your deployment is properly secured
No Secrets in Code: All sensitive configuration via environment variables

⁠License

MIT

Tag summary

Recent tags

Content type

Image

Digest

sha256:1d910778f…

Size

264 MB

Last updated

8 months ago

docker pull chenxizhang/claude-agent-web