Gluon AI编码智能体

Required (all backends): PUID, PGID, GH_TOKEN, GIT_USER_NAME, GIT_USER_EMAIL

Docker Quickstart

Run Gluon from a pre-built image — no clone or build required:

```bash

Installation (from source)

```bash

Create virtual environment and install

uv venv uv pip install -e .

Security & Isolation ([Docker](docs/DOCKER.md))

• OS-Level Sandboxing - Each agent runs inside a bubblewrap sandbox (Linux) or sandbox-exec (macOS), restricting filesystem access to the git worktree
• Git Worktree Isolation - Every task operates in its own worktree so agents never touch your main branch or other tasks' files
• Minimal Docker Runtime - python:3.12-slim-bookworm base with non-root gluon user; no full host filesystem access
• Scoped Volume Mounts - Only specific directories are mounted into the container (~/.claude, ~/.gluon, ~/workspaces), with common credentials (~/.aws, ~/.config/gh) mounted read-only
• Browser Session Isolation - Each agent run gets its own agent-browser session, preventing cross-task cookie/state leakage
• Sandbox-Aware Tool Approval - When sandboxed, bash commands are auto-approved (the sandbox enforces boundaries), while git is excluded from the sandbox to allow commits and pushes
• Resource Limits - Docker Compose enforces CPU and memory caps (default 8 CPU / 12 GB) to prevent runaway agents from starving the host

Multi-User Authentication (Optional · [full guide](docs/AUTH.md) · [OIDC setup](docs/AUTH-OIDC.md))

Self-hosted Gluon defaults to single-user mode — no login screen, every action runs as the implicit SYSTEM_USER. Flip GLUON_AUTH_ENABLED=true and Gluon becomes a true multi-user system:

• Local password auth - argon2id-hashed credentials in SQLite, DB-backed sessions (not JWT) with rolling TTL and httpOnly cookies.
• OIDC / SSO - Plug in Auth0, Google Workspace, AWS Cognito, Microsoft Entra ID, Okta, or any spec-compliant IdP. Auto-provision is opt-in with a required email-domain allowlist. Coexists with local — typical setup is OIDC for humans + a few local accounts for automation.
• Three roles - admin (full control), operator (create runs, decide approvals), viewer (read-only).
• Per-row attribution - every ExecutionRun, OrchestratorTask, and PendingApproval records who created or decided it, surfaced in the dashboard and the audit trail.
• Web dashboard - login page (auto-detects available providers and shows password form, "Sign in with X" button, or both), header user-menu with avatar + role badge + change-password, admin-only /admin/users screen (list / create / edit role / disable / reset password).
• Self-serve chat linking - users bind their Telegram or Discord identity to their Gluon account from the dashboard. Generate a one-time code, send /link <code> (Telegram) or link-account <code> (Discord) to the bot, done. Approvals from chat are then attributed to the right user.
• CLI bootstrap - seed the first admin without a chicken-and-egg login: gluon user add alice --role admin (local) or gluon user add alice --auth-provider oidc --email alice@org.example --role admin (OIDC). Other commands: gluon user list / show / disable / enable / set-role / set-password.
• Backwards-compatible - when GLUON_AUTH_ENABLED=false, no login UI, no role checks, attribution columns stay NULL. Existing single-user installs see zero behaviour change.

See docs/AUTH.md for the full architecture, login flow diagrams, RBAC model, attribution data model, transport linking flow, security properties, and migration story. docs/AUTH-OIDC.md covers OIDC-specific setup with provider-by-provider recipes.

Docker-Specific

Quick Start ([CLI Reference](docs/CLI-REFERENCE.md))

Choosing Your LLM Backend ([detailed guide](docs/LLM-PROVIDER.md))

Gluon talks to Claude through a pluggable provider abstraction. Pick whichever backend your organisation already uses — every feature (cost tracking, witness, approvals, budgets, session resume) works identically across all four.

```bash

Multi-User Auth (Optional · default off · [full guide](docs/AUTH.md))

See docs/AUTH-OIDC.md for provider-specific recipes (Auth0, Google Workspace, AWS Cognito, Microsoft Entra ID).

Web Dashboard ([docs](docs/WEB-DASHBOARD.md) · [screenshots](docs/SCREENSHOTS.md))

• Kanban Board - Drag-and-drop task management with Queue, Running, Review, and Done columns
• Real-Time Log Streaming - WebSocket-powered live log output with collapsible tool call visualization
• Run Details Modal - View messages, tool calls, commits, file diffs, and attachments
• Notification Center - Bell icon with unread count, persistent notification history, mark read/unread
• Global Question Modal - AskUserQuestion prompts appear as modal overlays from any page with run context (project, branch, task prompt), countdown timer, and multi-select/single-select support
• Full-Screen Mode - Expanded view for detailed run analysis
• Message Filtering - Filter by tools, text, or errors with counts
• Toast Notifications - Instant feedback for merge and PR actions
• Browser Notifications - Desktop push notifications for completed/failed runs and pending questions when tab is unfocused
• Recovery UI - Visual indicator when recovering interrupted runs with progress tracking
• Activity Feed - Cross-agent event stream showing run completions, PR actions, and system events
• Work Queue Panel - Queue and schedule tasks across projects from the dashboard
• Merge Queue Panel - Monitor and manage sequential PR merges with conflict status
• Formula Step Progress - Violet progress bar on run cards showing current step in multi-step workflows
• Witness Health Indicators - Real-time health classification dots on running tasks (healthy, slow, looping, stuck)
• Input Required Badges - Visual indicators on run cards when agents are waiting for user input

Browser Automation & Screenshots

• agent-browser - Pre-installed Chromium for headless browser automation (open, click, type, screenshot)
• Screenshot Interception - Screenshots captured via agent-browser screenshot are automatically stored as run attachments
• Inline Screenshot Messages - Screenshots appear as clickable thumbnails in both the Messages and Images tabs
• System Fonts - Docker image includes Liberation, Noto CJK, DejaVu, and FreeFonts for high-quality screenshot rendering

1. Download the compose file and env template

curl -fsSL https://raw.githubusercontent.com/carrotly-ai/gluon-agent/main/docker-compose.yml -o docker-compose.yml curl -fsSL https://raw.githubusercontent.com/carrotly-ai/gluon-agent/main/.env.example -o .env

2. Edit .env with your credentials

Optional extras:

uv pip install -e '.[discord]' # Discord bot uv pip install -e '.[web]' # Web dashboard uv pip install -e '.[all]' # All optional features ```

Requirements: Python 3.12+, Claude Code CLI installed and authenticated, uv package manager, credentials for your chosen LLM backend (AWS / GCP / Azure / Anthropic API key), Git, GitHub CLI (gh) optional.

Environment Variables

Bot Configuration

Anthropic → ANTHROPIC_API_KEY (or `claude login` session at ~/.claude)

Foundry → ANTHROPIC_FOUNDRY_RESOURCE + (API key or Entra ID via `az login`)

Core Capabilities ([CLI Reference](docs/CLI-REFERENCE.md))

• Multi-Project Management - Register projects and workspaces, run tasks across your entire codebase
• Session Resume - Continue Claude sessions with follow-up prompts, keeping full context
• Unified Task Tracking - All tasks visible across all interfaces (CLI, Web, Telegram, Discord)
• Model Selection - Choose between Haiku (fast), Sonnet (balanced), or Opus (complex tasks)
• Formula Workflows - YAML-defined multi-step pipelines (Plan → Implement → Test → Review) that execute as a single unified run
• Blueprint Validation - Automatic lint auto-fix, lint loop, and test gates after agent completion
• Work Queue - Shared task queue for batching and scheduling work items across projects
• Merge Queue - Sequential PR merge processing with conflict detection and retry
• System Diagnostics - Built-in doctor command for health checks and auto-fix

Per-task via API

curl -X POST http://localhost:45866/api/runs \ -H 'Content-Type: application/json' \ -d '{"project_id": "myapp", "prompt": "...", "agent_teams": true}'

**Prompt structure for best results:**

Agent teams work best when the prompt clearly decomposes into parallel subtasks. Structure prompts with explicit deliverables that subagents can own independently:

1. API layer — Update route handlers in src/api/auth.py to use the new token format
2. Database layer — Migrate the sessions table schema and update the ORM models
3. Tests — Add integration tests covering the new token flow and session expiry

Each area can be worked on independently. Coordinate at the end to ensure consistency. ```

Tips: - List 2-5 distinct subtasks that can run concurrently without blocking each other - Mention shared files or interfaces that subagents should be aware of - End with a synthesis instruction so the lead agent knows to reconcile the work - Pair with --model opus for the lead agent to get better task decomposition

See the Claude Code Agent Teams documentation for full details on how the underlying SDK orchestrates subagents.

Web Dashboard ([docs](docs/WEB-DASHBOARD.md) · [API](docs/API.md))

```bash gluon web

Natural Language Interface

Chat with Gluon using natural language:

"Run a task on myapp to fix the login bug" "What's the status of my running tasks?" "Show me the logs for the last task"

3. Run a Formula (Multi-Step Workflow)

```bash

Git Integration ([docs](docs/GIT-OPERATIONS.md))

• Worktree Isolation - Each task runs in its own git branch without affecting main
• PR Integration - Create PRs directly from the dashboard with one click
• Conflict Detection - Automatic detection of merge conflicts with file-level details
• AI Conflict Resolution - One-click to have Claude rebase and resolve merge conflicts
• Local & Remote Support - Works with both GitHub repos and local-only repositories

Formula Workflows

YAML-defined multi-step pipelines that execute as a single unified run. Each step gets its own Claude session but shares the same git worktree, run ID, and cost tracking.

Built-in formulas:

```bash

Gluon vs other Claude Code orchestrators

Table reflects published features as of 2026-04. See each project's README for current state; this is not a sponsored comparison.