convez.ai
Agente
jakubro

claudebox

jakubro/claudebox

Ver no GitHub
InicialPluginScore · de 0 a 100

Containerized isolation, customizable agent profiles, and a visual web UI — for AI coding agents.

Instalação

$npx convez-ai jakubro/claudebox

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 dias
Versão
—
Issues abertas
2
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

Claudebox

License: GPL v3 Version Status

Containerized isolation, customizable agent profiles, and a visual web UI — for AI coding agents.

Claudebox runs AI coding agents in disposable containers — one per session, full agent capabilities, controlled host exposure. Claude Code via the Claude Agent SDK by default, or any LangChain provider (Ollama, OpenAI, Gemini, and more) via LangGraph. Profiles layer in system prompts, hooks, commands, skills, agents, and custom tools — install and customize what each project needs. The web interface renders the full conversation — markdown, code, diffs, and diagrams — while dockable panels let you manage sessions, track tasks, browse and edit files, queue follow-up messages, switch between sessions, and fork at any point in history: a multi-panel workspace the terminal can't replicate.

Prerequisites

  • Podman or Docker
  • Git
  • Bash
  • Python 3.11+ (managed via uv, installed automatically if not present)
  • Node.js 24+ (managed via nvm, installed automatically if not present)

Installation

# Podman (default)
curl -LsSf https://raw.githubusercontent.com/jakubro/claudebox/main/bin/install.sh | bash

# Docker
CLAUDEBOX_BACKEND=docker curl -LsSf https://raw.githubusercontent.com/jakubro/claudebox/main/bin/install.sh | bash

# Then open https://localhost:41820

This clones the library, builds the frontend and container image, installs the claudebox CLI and claudeboxd daemon, registers the daemon as a systemd user service, and installs a daily maintenance timer that rebuilds the container image.

First install builds a three-layer container image (base, profile, agent) — expect 5-15 minutes on first run depending on network and CPU.

Quick Start

# First run — authenticate via TUI (one-time)
claudebox run

The first launch opens the Claude Code TUI where you complete authentication. Credentials persist across sessions within the same workspace (or globally when no .workspace marker is set). After login, you can use either TUI or web mode.

The web UI is served by claudeboxd, a daemon installed during setup, at https://localhost:41820. Caddy fronts the daemon with a self-signed TLS certificate; your browser will show a one-time certificate warning that's safe to accept. The daemon manages container lifecycles and proxies requests to the per-session container API.

On systems without systemd (e.g. macOS), the daemon service is not installed automatically. Start it manually with claudeboxd.

Configuration

Claudebox looks for .claudebox/settings.toml files walking up from your current directory and deep-merges them (nearest wins). This lets you keep shared defaults at ~/.claudebox/settings.toml and project-specific overrides inside each workspace.

# Stop searching for settings.toml in parent directories
root = true

# Path to profile directory containing Claudebox customizations
profile = "~/.claudebox/profile"

# AI agent to launch inside container (default: "claude")
agent = "claude"

# Container runtime (default: "podman")
backend = "podman"

# Volume mounts: host path → container path
[mounts]
"/data/models" = "/models"

# Port forwarding: host port → container port (use 0 for random host port)
[ports]
8080 = 80

# Container network mode
[network]
mode = "slirp4netns:allow_host_loopback=true"

# Environment variables passed to the container
[env]
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = 1

Your workspace directory is automatically mounted at the same path inside the container — no configuration needed. See etc/settings.sample.toml for a commented template of every key.

Profiles

Profiles customize the container environment, system prompts, and lifecycle hooks. A profile directory can contain:

profile/
├── hooks/
│   ├── container-start.sh # Sourced on container init
│   ├── container-end.sh   # Sourced on container exit
│   ├── agent-start.sh     # Executed on agent session start
│   ├── agent-stop.sh      # Executed on agent session end
│   └── image-build.sh     # Custom profile image layer
└── prompt.md              # System prompt entry point

Prompt compiler. The prompt system supports {{ }} interpolation for modular prompt composition:

SyntaxResolution
{{ relative/path }}Include file relative to the prompt file, recursively interpolated
{{ @path }}Include file relative to workspace root
{{ /absolute/path }}Include absolute path as-is
{{ !function }}Call a fn_function() bash function (built-ins: !path for cwd, !tree for filtered directory listing)

Indentation is preserved: when {{ content }} appears indented, all included lines inherit the same indent prefix.

Claude Code SDK hooks. In addition to shell lifecycle hooks, profiles can include Python hooks processed by the @hook and @statusline decorators. These integrate with the Claude Code hook system (SessionStart, PreToolUse, PostToolUse, etc.) for programmatic control over agent behavior.

Point your config at a profile with profile = "/path/to/profile". See etc/profile.sample/ for a working example with modular prompts, lifecycle hooks, a multi-agent review command, and an MCP skill.

Workspaces

Without a .workspace marker, claudebox runs unscoped and stores all state on the host at ~/.claudebox/.

For per-project isolation, create a .workspace marker file in your project root:

touch .workspace

With a marker in place, claudebox stores everything under {workspace}/.claudebox/ instead — sessions, Claude credentials, and UI state stay scoped to that project. This is the recommended setup when working across multiple projects.

Storage layout (relative to whichever root is active):

PathContents
.claudebox/settings.tomlSettings — overrides the global ~/.claudebox/settings.toml
.claudebox/sessions/YYYYMMDD-HHMMSS--{session_id}/Per-session data, events, logs
.claudebox/fs/root/.claude.jsonClaude Code auth/config file (mounted into the container)
.claudebox/fs/root/.claude/Claude Code config directory (settings, commands, skills)

Daemon registration. Workspaces register with the daemon via claudebox workspaces register. Only registered workspaces appear in the web UI workspace switcher.

Multi-workspace mode. The daemon tracks all registered workspaces and exposes them through the web UI. When multiple workspaces are registered, a workspace switcher dropdown appears in the Session Header Strip. Sessions, containers, and UI state are fully isolated per workspace. URL hash forms for deep linking:

Hash formMeaning
#/workspaces/{id}Welcome state, no active session
#/workspaces/{id}/sessions/{sid}Active session, view scrolled to the latest message
#/workspaces/{id}/sessions/{sid}/turns/u-{tid}Paused at a user message
#/workspaces/{id}/sessions/{sid}/turns/a-{tid}Paused at an assistant message
#/workspaces/{id}/boards/{bid}Active ticket board

Web UI

The web UI provides a full-featured chat interface with a dockable panel system. Each browser tab hosts exactly one session — multiple sessions = multiple browser tabs. Each session runs in its own container; creating, resuming, or forking a session spins up a dedicated container that is removed when you close the browser tab.

Layout

┌─────────────┬─────────────────────────────────┬───────────────────┐
│ Session Header Strip:  status · name · Stop · + · Workspace ▾     │
├─────────────┼─────────────────────────────────┼───────────────────┤
│ Sessions    │            Chat                 │  Todos            │
│             │                                 │  Stash            │
│             │                                 │  Tasks            │
│             │                                 │  Bookmarks        │
│             │                                 │  Boards           │
│             │                                 │  Usage            │
│             │                                 │  MCP              │
│             │                                 │  Skills           │
│             │                                 │  Help             │
├─────────────┼─────────────────────────────────┼───────────────────┤
│ Containers  │                                 │  Logs             │
├─────────────┴─────────────────────────────────┴───────────────────┤
│ Footer: workspace · cost · context · model · effort · permission  │
│         · session id · notifications · service status             │
└───────────────────────────────────────────────────────────────────┘

Panels toggle from icon strips on the left (Sessions, Containers) and right (Todos, Stash, Tasks, Bookmarks, Boards, Usage, MCP, Skills, Help, Logs) edges. Double-click a tab to maximize; middle-click closes a side panel tab (except Chat — Chat is always visible). All panel sizes and visibility persist across sessions. Workspace accent colors tint the tab bar gradient for quick visual identification.

Chat

  • Real-time streaming responses with markdown rendering, syntax-highlighted code blocks, and mermaid diagrams
  • Collapsible tool blocks with formatted summaries (file diffs, grep results, search hits)
  • Inline interactive forms — answer questions and review plans without leaving the chat
  • Drag-drop or paste file/image attachments
  • Input history (Up/Down), draft persistence, and auto-resize textarea
  • XML block folding in the input area (Ctrl+' to collapse, Ctrl+\ to expand)
  • Rewind to any user message — fork here (replaces current session) or fork in new browser tab
  • Turn-level copy buttons, collapsible turns, duration and timestamp badges
  • Slash command autocomplete — type / at the start of input for a substring-matched dropdown of available commands

Minimap

A proportional conversation overview rendered alongside the chat:

  • Each turn shown as a colored segment scaled to its content height
  • Click or drag to scroll the conversation
  • Visible-area indicator tracks current scroll position
  • Yellow markers for bookmarked turns
  • Toggleable via control bar button — state persists

Message Queue

Queue follow-up messages while Claude is still responding:

  • Alt+Enter queues a message instead of sending it immediately
  • Queued messages appear as dimmed bubbles below the current response
  • Queue drains FIFO — each response completion auto-sends the next message
  • Hover a queued bubble for send-now, edit, or cancel actions
  • Interrupts and errors pause the queue; re-queue or cancel paused messages
  • Queue persists per session across page reloads

Sessions

  • Create, resume, rename, and pin sessions
  • Session tree with fork hierarchy — rewinds nest under their parent
  • Session prompt editor — inject per-session context that survives compaction (re-injected after each compaction)
  • Cost tracking per session and aggregated in the Usage panel (24h / 7d / 30d / all-time)

Todos

  • Real-time todo list showing current tasks from the agent
  • Status icons: pending (○), in progress (◐), completed (●)
  • Subagent segmentation — todos grouped by the task that created them
  • Badge count on the icon strip shows incomplete items

Tasks

  • Monitor background tasks spawned by the agent
  • Filter between active (running) and all tasks
  • Live duration tracking with staleness indication
  • Click a task to jump to it in the chat

Stash

Temporary text clipboard for storing and retrieving prompts. Ctrl+S to stash current input, Ctrl+Shift+S to pop.

Bookmarks

  • Bookmark any user message turn — toggle via button on hover
  • Bookmarks panel (Alt+5) with "This session" and "All sessions" tabs
  • Click a bookmark to scroll to the turn; remove on hover
  • Yellow minimap indicator for bookmarked turns
  • Cross-tab sync — bookmarks update across browser tabs automatically

Boards

Kanban-style ticket boards:

  • Multiple swimlanes per board with configurable states (e.g. backlog → in-progress → done)
  • Ticket cards with title, ID, assignee, and metadata; click to open detail overlay
  • Drag-and-drop tickets between states and swimlanes
  • Multi-select for bulk move and archive
  • Density modes (comfortable / terse) for fitting more cards on screen
  • Real-time updates across browser tabs viewing the same board

MCP

  • Server connection status with colored indicators (connected/disconnected/failed)
  • Reconnect button for failed servers, disable/enable toggle for all servers
  • Loading spinner during actions, error messages with auto-clear

Footer

Workspace, API cost, context usage bar with color gradient, model picker, effort level picker, permission mode picker, session ID, notification toggle, and Claude service status indicator (sourced from status.claude.com).

The model, effort level, and permission mode indicators are interactive dropdowns — click to switch mid-conversation.

Keyboard Shortcuts

ShortcutAction
EnterSend message
Alt+EnterQueue message
Shift+EnterNew line
TabIndent
Shift+TabDedent
Ctrl+.Interrupt response
Up / DownInput history
Ctrl+SStash input
Ctrl+Shift+SPop from stash
Ctrl+,Wrap selection in <this></this>
Ctrl+'Collapse nearest XML block
Ctrl+Shift+'Collapse all XML blocks
Ctrl+\Expand nearest collapsed block
Ctrl+Shift+\Expand all collapsed blocks
Alt+Up / Alt+DownJump to previous/next user message
Alt+Home / Alt+EndJump to first/last message
Alt+CFocus Chat
Alt+0Toggle Logs
Alt+1Toggle Sessions
Alt+2Toggle Todos
Alt+3Toggle Stash
Alt+4Toggle Tasks
Alt+5Toggle Bookmarks
Alt+6Toggle Boards
Alt+7Toggle Usage
Alt+8Toggle MCP
Alt+9Toggle Skills
Alt+? (or Alt+/)Help overlay
Alt+NNew session
Alt+Shift+NNew session in new tab

Notifications

  • Desktop notifications and sound chime when a response completes while the tab is unfocused
  • Favicon animation while Claude is working
  • Tab title indicator (*) for unread responses

Multi-runtime support

By default Claudebox runs Claude via the Claude Agent SDK. Set agent = "langgraph" to run on LangGraph instead, which talks to any LangChain-supported provider — Ollama, Anthropic, OpenAI, Google Gemini, Groq, Mistral, AWS Bedrock, and more. All provider packages ship preinstalled, so switching is config-only: set the model and credentials, then relaunch.

Configuration

Add a [langgraph] block to settings.toml (global ~/.claudebox/settings.toml or per-workspace — they deep-merge):

agent = "langgraph"

[langgraph]
model = "anthropic:claude-sonnet-4-5"   # "provider:model-id" form

[langgraph.ollama]
base_url = "http://host.containers.internal:11434"   # Ollama on the host

The model id follows LangChain's init_chat_model convention. Common providers:

ProviderEnv varmodel =
AnthropicANTHROPIC_API_KEY"anthropic:claude-sonnet-4-5"
OpenAIOPENAI_API_KEY"openai:gpt-4o"
Google GeminiGOOGLE_API_KEY"google_genai:gemini-2.5-pro"
GroqGROQ_API_KEY"groq:llama-3.3-70b-versatile"
MistralMISTRAL_API_KEY"mistralai:mistral-large-latest"
Ollamanone"ollama:llama3.2:3b"
Local OpenAI server (vLLM, LM Studio, llama.cpp)none"openai:<model>" + [langgraph.openai] base_url

Anthropic, OpenAI, and Ollama are tested in CI; the other providers ship in the image and are user-supported. LangGraph workspaces also support MCP servers via [langgraph.mcp.<name>] blocks and a configurable web_search backend — see etc/settings.sample.toml for every knob.

What's different under LangGraph

LangGraph binds the same core tools (filesystem, search, shell, web, MCP), but some Claude-only UI surfaces are hidden because the runtime doesn't support them: the effort picker, permission-mode picker, mid-session model picker, skills autocomplete, manual /compact button, and MCP control panel.

Model calls, web_fetch/web_search, and [langgraph.mcp.*] servers all make outbound requests from the container. The container's network policy is the real boundary — review your configured providers before adopting in privacy-sensitive workspaces.

Advanced

CLI Reference

claudebox — verb-mode CLI

claudebox [-v] <command> [options] [-- agent-args]
CommandDescription
runLaunch agent session in container
buildBuild container image
updateRefresh Claudebox itself (re-runs install.sh; concurrent runs blocked by flock)
shellOpen bash shell in fresh container
pruneRemove stopped containers, dangling images, stale dirs
logsStream logs — daemon (default) tails the daemon log; all multiplexes daemon + every container with source prefixes
statusShow daemon + containers + workspace state in three rows (degraded mode when daemon is down)
doctorDiagnose environment readiness — runs ordered checks and prints ✓/✗/○ per row
versionPrint version, branch, commit, install path, python and podman versions
daemonManage host daemon — start / stop / restart / status (systemd --user wrappers)
containersManage containers — list / stop / kill across all workspaces (prefix resolution; all for fan-out)
workspacesManage registered workspaces — list / register [path] / deregister <id>

Global flag: -v / --verbose is accepted before or after the verb (e.g. claudebox -v build and claudebox build -v are equivalent). claudebox logs accepts --tail <N> and --no-follow for backfill control. Run claudebox <command> --help for command-specific options.

Examples:

claudebox run                     # interactive agent session
claudebox run -- --resume         # resume the most recent agent conversation
claudebox run -- -p "prompt"      # non-interactive print mode
claudebox build                   # cached build (reuses all layers)
claudebox build --layer all       # full rebuild from base
claudebox build --layer agent     # rebuild agent layer only
claudebox shell                   # bash shell in fresh container
claudebox prune                   # summary count of removed resources
claudebox -v prune                # list each removed item

claudeboxd — Web UI daemon

claudeboxd [flags]
FlagShortDescription
--port-pDaemon port (default: 41820)
--dev-dDevelopment mode — uvicorn with hot reload for the API, Vite dev server for the frontend

The container image is built in three layers, each rebuilt at different frequencies:

LayerContentRebuild frequency
BaseSystem packages, mise, Python 3.13, Node 24, uv, Rust, just, ghRare (Containerfile changes)
ProfileCustom tools installed by the profile's image-build.sh hookOn profile change
AgentClaude Code CLI (via mise) + Python dependencies (uv sync)On build --layer agent

build rebuilds all layers with caching. build --layer agent forces only the agent layer to rebuild (fast update for new Claude Code versions). build --layer all discards all caches.

Maintenance

Claudebox ships with a systemd timer that rebuilds the agent layer of the container image daily to keep Claude Code and dependencies up to date. The timer is installed automatically during setup.

On macOS or systems without systemd, run maintenance manually:

claudebox update

This pulls the latest library, rebuilds the container image, and prunes old containers. (The underlying script lives at ~/.claudebox/lib/bin/install.sh and can be invoked directly as a fallback.)

Update

To update Claudebox itself (library + container image):

claudebox update

Same code path as fresh install — it detects an existing installation and reinstalls in place (library, frontend build, systemd units, container image). Concurrent invocations are blocked by an flock inside the install script; the second invocation exits non-zero immediately. The underlying script (~/.claudebox/lib/bin/install.sh) can still be invoked directly when needed.

Logs

Daemon logs live under ~/.claudebox/logs/. Per-session logs live inside each session directory (.claudebox/sessions/.../). When the daemon runs under systemd:

journalctl --user -u claudebox-daemon.service -f

For verbose CLI output, pass --verbose/-v. For a dev-mode daemon (hot-reload + Vite HMR), run claudeboxd --dev.

Architecture

Claudebox is organized into five packages:

PackageRole
claudeboxCore framework — workspace discovery, config loading, hook system, container abstraction. Shared by all other packages.
claudebox_cliHost-side CLI entry point. Parses arguments, builds container images, launches TUI containers. Registers workspaces via workspaces register.
claudebox_daemonHost-side daemon (FastAPI). Orchestrates multiple workspaces and containers, proxies requests to container APIs, manages session lifecycle (create, resume, fork). Serves the frontend in production over HTTPS via a Caddy reverse proxy.
claudebox_container_apiIn-container API server (FastAPI). Bridges the agent runtime (Claude Agent SDK or LangGraph) and the frontend via HTTP and SSE. One instance per container.
claudebox_frontendVite-built React 19 SPA. Communicates with the daemon and container APIs. Dockview-based panel layout.
flowchart LR
  subgraph Browser
    Frontend["claudebox_frontend<br/>(Vite + React 19 SPA)"]
  end
  Caddy["Caddy<br/>(TLS proxy)"]
  Daemon["claudeboxd<br/>(host)"]
  CLI["claudebox<br/>(host CLI)"]
  subgraph Container
    API["claudebox_container_api"]
    Runtime["Agent runtime<br/>(Claude Agent SDK / LangGraph)"]
  end

  Frontend -- "HTTPS :41820" --> Caddy
  Caddy --> Daemon
  Daemon -- "serves SPA bundle" --> Frontend
  CLI -- "build / run" --> Container
  Daemon -- "lifecycle + proxy" --> API
  API --> Runtime

Troubleshooting

SymptomRemediation
Certificate warning on first visitSelf-signed cert from Caddy — safe to accept once per browser
First run very slow (~10 min)First install builds the container image; subsequent runs reuse cached layers
claudeboxd not running (no UI)systemctl --user status claudebox-daemon.service; on macOS run claudeboxd manually
Port 41820 already in useclaudeboxd --port <other> or kill the conflicting process
Podman socket / XDG_RUNTIME_DIR errorsEnsure rootless podman is configured: podman system migrate, verify XDG_RUNTIME_DIR is set
Container fails to startclaudebox --verbose to see the full podman run command; check logs
Stale containers / disk pressureclaudebox prune (or claudebox -v prune for per-item output)
Need daemon/container logsjournalctl --user -u claudebox-daemon.service -f (systemd) or ~/.claudebox/logs/

Security

Claudebox's trust boundary is the container. Agents run with --permission-mode bypassPermissions and can execute anything inside their container. The container, in turn, has read/write access to the workspace directory (mounted at the same path inside and outside).

  • Inside the container: agent has full filesystem access to the workspace, full network access, and can install packages.
  • Outside the workspace: protected by the container boundary — agent cannot read or write host files outside the mounted workspace.
  • Daemon network surface: Caddy listens on all interfaces at the configured port (default 41820) with a self-signed TLS certificate. There is no built-in auth on the HTTP surface, so anyone with network access to the host can reach the daemon. Bind to localhost, firewall the port, or front with an authenticated reverse proxy if hosting on a network you don't control.
  • Credentials: Claude Code's auth token lives at .claudebox/fs/root/.claude.json (per-workspace) or ~/.claudebox/fs/root/.claude.json (global). Treat these as you would any other API token.

Claudebox itself is telemetry-free.

Contributing

git clone https://github.com/jakubro/claudebox.git
cd claudebox/lib
just install          # python + frontend + e2e deps
just check            # full pre-commit (lint + test)
just --list           # all recipes, grouped

Coding conventions, testing patterns, and the development workflow are documented in docs/GUIDELINES.md. All development commands run from lib/ via the justfile.

Uninstall

# Stop and disable systemd units
systemctl --user disable --now claudebox-daemon.service claudebox-maintenance.timer
rm -f ~/.config/systemd/user/claudebox-*
systemctl --user daemon-reload

# Remove CLI symlinks
rm -f ~/.local/bin/claudebox ~/.local/bin/claudeboxd

# Remove library, state, and credentials (irreversible)
rm -rf ~/.claudebox

# Remove containers and images
podman container prune -f --filter label=app=claudebox
podman image prune -f --filter label=app=claudebox

Limitations

  • Linux-first: Full automation (systemd daemon + maintenance timer) requires systemd. macOS works without auto-start; daemon must be launched manually.
  • Single-host: claudeboxd is intended for the local machine. It listens on all interfaces by default but has no built-in auth, so exposing it on an untrusted network requires fronting it with an authenticated reverse proxy.
  • Single-user: One user per host; no multi-tenant isolation beyond podman's rootless boundary.
  • Container runtime: Podman or Docker. Other OCI runtimes untested.

Further Reading

  • Architecture — subsystems, data flow, component ownership
  • Specification — full user-facing behavior specification
  • Guidelines — coding conventions, development setup, and testing
  • Test UI — in-container Playwright harness for live debugging

Acknowledgements

Built on Claude Code and the Claude Agent SDK. Uses LangGraph and LangChain for multi-provider runtime support, plus FastAPI, Vite, React, Dockview, Playwright, Caddy, uv, nvm, Podman, and Docker.

License

Copyright (C) 2025-2026 Jakub Roman. Distributed under the GNU GPL v3.

Ver o original no GitHub

Bom para

Relacionados