Gluon Agent
carrotly-ai/gluon-agent
Orquestrador multi-cloud para agentes Claude Code em Docker com dashboard e controle remoto
Ver no GitHubOrquestrador self-hosted para Claude Code que executa agentes de IA em paralelo dentro de containers Docker isolados. Integra-se com múltiplos backends (AWS Bedrock, Google Vertex AI, Azure AI Foundry, Anthropic API), oferecendo controle via CLI, dashboard web, Telegram e Discord com persistência de sessão e isolamento de worktrees.
Instalação
npx convez-ai carrotly-ai/gluon-agent1 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
Casos de uso
- Executar múltiplas tarefas de desenvolvimento de features em paralelo
- Delegar correções de bugs a agentes IA enquanto você gerencia arquitetura
- Gerenciar backlog de tarefas assistidas por IA em múltiplos projetos
- Integração com pipelines DevOps usando Bedrock, Vertex ou Foundry
Veredito

Solução robusta para equipes que precisam de controle total sobre infraestrutura de agentes Claude Code. Requer conhecimento sólido de Docker, Python e cloud providers, mas oferece flexibilidade máxima em backend LLM e rastreabilidade completa das execuções.
README
A tradução para o português deste README ainda está na fila.
Gluon Agent
Self-hosted orchestrator for Claude Code. Run fleets of AI coding agents from your own infrastructure — with session persistence, git worktree isolation, and remote control from CLI, web dashboard, Telegram, or Discord. Agents run in a containerized Docker environment with bubblewrap sandboxing.
Bring your own backend — Gluon routes inference through whichever Claude backend your organisation already pays for: AWS Bedrock, Google Vertex AI, Microsoft Foundry (Azure AI Foundry), or the direct Anthropic API / Claude CLI subscription. Switch between them with one command (gluon provider <name>) or from the Settings page. See docs/LLM-PROVIDER.md for the full provider guide.


See all screenshots in docs/SCREENSHOTS.md
Table of Contents
- Why Gluon?
- Docker Quickstart
- Installation (from source)
- Quick Start (CLI)
- Choosing Your LLM Backend
- Features
- Web Dashboard
- Chat Bots
- Architecture
- Model Selection
- Documentation
- Data Storage
- Environment Variables
- Remote Access
- License
Why Gluon?
Three things most Claude Code orchestrators don't give you:
1. You own the agents. Docker compose, your server, your data. ~/.gluon
holds the full SQLite database and every run log — nothing leaves your
infrastructure. Mount ~/.claude and ~/.aws from the host and the container
uses your existing credentials.
2. Pluggable LLM backends. Gluon ships with a provider abstraction that
speaks AWS Bedrock, Google Vertex AI, Microsoft Foundry, and the direct
Anthropic API. Use whichever your organisation already bills through —
Gluon exports the right CLAUDE_CODE_USE_* flag, wires in the right
credentials, and resolves the right model IDs automatically. Pay per-token
at your cloud's rates, cap spend per run, and keep running if any one
provider changes plans underfoot.
3. Control from anywhere. Kick off a task from your desk via CLI or web, approve the PR from your phone via Telegram, review failures in Discord while you're at lunch. All four transports talk to the same orchestrator and see the same runs.
Well-suited for
- Running several feature implementations simultaneously across a project
- Delegating bug fixes to AI agents while you focus on architecture
- Managing a backlog of AI-assisted tasks across multiple projects
- Teams that want visibility into AI-assisted development work
- Operators who need Bedrock-, Vertex-, or Foundry-native deployment for compliance or cost reasons
Gluon vs other Claude Code orchestrators
| Gluon | Claude Deck | claudectl | KingCoding | |
|---|---|---|---|---|
| Self-hosted | ✅ | ✅ | ✅ | ❌ |
| Multi-cloud LLM backend (Bedrock + Vertex + Foundry + direct) | ✅ | ❌ | ❌ | ❌ |
| Multi-transport (CLI+TG+Discord+Web) | ✅ | Web only | CLI only | Mobile only |
| Session resume (fork_session) | ✅ | — | — | — |
| Git worktree isolation + GC | ✅ | — | Partial | — |
| Witness auto-recovery | ✅ | — | — | — |
| Background execution | ✅ | ✅ | ✅ | ✅ |
| Docker one-liner | ✅ | ✅ | — | — |
| Work queue (self-propelling) | ✅ | — | Partial | — |
Table reflects published features as of 2026-04. See each project's README for current state; this is not a sponsored comparison.
No really, why the name Gluon?
Because every team needs a fundamental force for getting things (and code) to stick together.
In physics, a gluon is a massless, spin-1 gauge boson — in plain speak, it's the subatomic "glue" holding quarks together, keeping protons, neutrons, and the heart of atoms from flying apart like a badly managed project. Gluons do the heavy lifting in quantum chromodynamics, ensuring that the universe, as well as your software, doesn't unravel at the seams.
So, like its namesake, Gluon binds together your scattered projects and tasks, orchestrating collaboration with the (strong) force of a particle accelerator and the finesse of quantum mechanics. Strong interaction? That's our vibe.
Docker Quickstart
Run Gluon from a pre-built image — no clone or build required:
# 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
# Required (all backends): PUID, PGID, GH_TOKEN, GIT_USER_NAME, GIT_USER_EMAIL
# Then pick ONE provider block (Bedrock is the default):
# Bedrock → AWS_REGION + AWS_BEARER_TOKEN_BEDROCK (or AWS access keys)
# Anthropic → ANTHROPIC_API_KEY (or `claude login` session at ~/.claude)
# Vertex → ANTHROPIC_VERTEX_PROJECT_ID + CLOUD_ML_REGION + gcloud ADC
# Foundry → ANTHROPIC_FOUNDRY_RESOURCE + (API key or Entra ID via `az login`)
# Find your UID/GID with: id -u && id -g
# 3. Start the container
docker compose up -d
# 4. Open the dashboard
open http://localhost:45866
The image is published to ghcr.io/carrotly-ai/gluon-agent:latest on every push to main.
Prerequisites: Docker, a Claude Code CLI auth session at
~/.claude, and cloud credentials for your chosen provider:
Provider Credentials AWS Bedrock (default) ~/.aws(mounted read-only)Anthropic Direct ANTHROPIC_API_KEYenv var or~/.claudeloginGoogle Vertex AI ~/.config/gcloud(rungcloud auth application-default login)Microsoft Foundry ~/.azure(runaz login) orANTHROPIC_FOUNDRY_API_KEYenv var
Docker Features:
- PUID/PGID Support - Container adapts to any host user's UID/GID — no permission issues with bind mounts
- HTTPS Git Authentication - Uses
GH_TOKENfor GitHub access (no SSH keys needed) - MCP Server Auto-Registration - Mount
.mcp.jsonto auto-register MCP servers on startup - Pre-built Image -
ghcr.io/carrotly-ai/gluon-agent:latestupdated on every push tomain
See DOCKER.md for detailed deployment instructions, building from source, and docker-compose.dev.yml for local development.
Installation (from source)
# Clone the repository
git clone https://github.com/carrotly-ai/gluon-agent.git
cd gluon-agent
# Create virtual environment and install
uv venv
uv pip install -e .
# Telegram bot support is included in the base install above.
# 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.
Quick Start (CLI Reference)
1. Register a Project
gluon project add myapp ~/projects/myapp
2. Run a Task
# Interactive mode (see output in terminal)
gluon run myapp 'Fix the authentication bug in login.py'
# Background mode (monitor via dashboard)
gluon run myapp 'Implement user registration' --background
# Use git worktree for isolated branch
gluon run myapp 'Add dark mode support' --background --worktree
3. Run a Formula (Multi-Step Workflow)
# Full feature lifecycle: Plan → Implement → Test → Review
gluon formula run feature myapp --var description="Add dark mode support"
# Bug diagnosis and fix: Diagnose → Fix → Test
gluon formula run bugfix myapp --var description="Login fails on expired tokens"
4. Resume with Follow-up
# Continue the conversation
gluon resume myapp 'Also add unit tests for the new code'
5. Monitor Progress
# Check all runs
gluon runs
# View specific run logs
gluon logs <run-id>
gluon logs <run-id> -f # Follow live
Choosing Your LLM Backend (detailed guide)
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.
# View current provider + model mappings
gluon provider
# Switch backend (persists to the DB)
gluon provider bedrock # AWS Bedrock (default)
gluon provider anthropic # Direct Anthropic API / Claude CLI subscription
gluon provider vertex # Google Vertex AI
gluon provider foundry # Microsoft Foundry (Azure AI Foundry)
Or set GLUON_LLM_PROVIDER=<name> in .env, or toggle from the dashboard Settings page.
| Backend | Model ID scheme | Credentials |
|---|---|---|
| AWS Bedrock (default) | global.anthropic.claude-sonnet-4-6 | AWS env or ~/.aws |
| Anthropic Direct | claude-sonnet-4-6 | ANTHROPIC_API_KEY or claude login |
| Google Vertex AI | claude-sonnet-4-6 / claude-haiku-4-5@20251001 | GCP ADC (gcloud auth application-default login) |
| Microsoft Foundry | claude-sonnet-4-6 (your Azure deployment name) | ANTHROPIC_FOUNDRY_API_KEY or az login |
Gluon automatically exports the matching CLAUDE_CODE_USE_* flag into the Claude Code subprocess and resolves model IDs to the active provider's scheme, so the same --model sonnet works everywhere.
Resolution order: explicit argument → GLUON_LLM_PROVIDER env var → llm_provider setting in the DB → default bedrock.
Features
Core Capabilities (CLI Reference)
- 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
doctorcommand for health checks and auto-fix
Security & Isolation (Docker)
- 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-bookwormbase with non-rootgluonuser; 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-browsersession, 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 · OIDC setup)
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, andPendingApprovalrecords 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/usersscreen (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) orlink-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) orgluon 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.mdfor the full architecture, login flow diagrams, RBAC model, attribution data model, transport linking flow, security properties, and migration story.docs/AUTH-OIDC.mdcovers OIDC-specific setup with provider-by-provider recipes.
Web Dashboard (docs · screenshots)
- 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
Progressive Web App (PWA)
- Installable App - Install on mobile/desktop for native-like experience
- Offline Support - Service worker caching with offline state detection
- Pull-to-Refresh - Native mobile gesture for refreshing in PWA mode
- Animated Offline Indicator - Friendly visual feedback when connection lost
- Update Notifications - Banner alerts when new version is available
Git Integration (docs)
- 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
Chat Bot Features (Telegram · Discord)
- Natural Language Interface - Chat with Gluon using natural language commands
- 40+ MCP Tools - Comprehensive tools for project, git, branch, and conflict management
- Discord DM Support - Run tasks via direct messages with project specifiers (
project:myapp) - Model Selection via Flags - Use
--model opusin Discord/Telegram to specify models - Channel Topic Config - Configure default project and model via Discord channel topics
- Tool Call Visualization - See agent tool calls in real-time during execution
Ralph Loop (Autonomous Mode) (docs)
- Autonomous Execution - Claude works continuously until task completion
- Completion Detection - RALPH_STATUS blocks, keyword matching, TODO file parsing
- Circuit Breaker - 3-state machine prevents runaway loops (CLOSED → HALF_OPEN → OPEN)
- Rate Limiting - Hourly API call limits and optional cost caps
- Supervision Daemon - Background auto-resume for tasks in REVIEW status
- Session Continuity - Claude maintains context across loop iterations
# Start autonomous ralph run
gluon run myapp "Implement auth system" --ralph --max-loops 50 --max-cost 10
# Monitor progress
gluon ralph status <run_id>
# Start supervisor daemon for auto-resume
gluon supervisor start
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:
| Formula | Steps | Description |
|---|---|---|
feature | Plan → Implement → Test → Review | Full feature development lifecycle |
bugfix | Diagnose → Fix → Test | Bug diagnosis and resolution |
# List available formulas
gluon formula list
# Run a feature formula
gluon formula run feature myapp --var description="Add user authentication"
# Run a bugfix formula
gluon formula run bugfix myapp --var description="Login fails on expired tokens"
# Validate a custom formula template
gluon formula validate my-formula.yml
How it works:
- The first step creates an
ExecutionRunin a git worktree - Subsequent steps resume the same run with
fresh_session=True— new Claude session, same worktree - The Kanban board shows a single card with a step progress bar (e.g., "Step 2/4 Implement")
- Cost accumulates across all steps on the single run
Custom formulas: Place .yml files in ~/.gluon/formulas/ (user-level) or .gluon/formulas/ (project-level). Built-in formulas ship in src/gluon/formulas/.
Blueprint Validation
Automatic code quality gates that run after each agent completion (for standard profile steps):
- Auto-fix — Runs the project's linter with auto-fix (e.g.,
ruff check --fix && ruff format .) - Lint loop — If lint errors remain, the agent is resumed to fix them (up to 3 attempts)
- Test gate — Runs the project's test suite; failures trigger an agent resume to fix
Blueprint validation is enabled by default and can be toggled in the web dashboard Settings. It only runs for standard profile steps — planning and review profiles skip validation.
Work Queue & Merge Queue
Work Queue — Batch and schedule tasks across projects:
gluon queue add myapp "Implement feature X"
gluon queue list
gluon queue cancel <item-id>
Merge Queue — Sequential PR merge processing with conflict detection:
gluon merge list
gluon merge retry <entry-id>
gluon merge cancel <entry-id>
Both queues are accessible from the web dashboard with real-time WebSocket updates.
Witness Health Monitor
Background health classification for running agents. The witness periodically evaluates agent behavior and classifies runs as:
| Classification | Meaning |
|---|---|
healthy | Normal progress |
slow | Below expected throughput |
looping | Repeating similar actions |
stuck | No meaningful progress |
zombie | Process alive but unresponsive |
gluon witness <run-id>
Health status appears as colored dots on running task cards in the web dashboard.
System Diagnostics
# Check system health
gluon doctor
# Auto-fix fixable issues
gluon doctor --fix
gluon doctor fix
Checks Claude CLI availability, AWS credentials, database integrity, disk space, and more.
Activity Log
Cross-agent event stream showing run completions, PR actions, merge queue events, and system events:
gluon activity
Also available as a dedicated panel in the web dashboard.
Agent Teams (Experimental)
Leverage Claude Code's Agent Teams capability to have a lead agent coordinate multiple subagents working in parallel on different parts of a task. Gluon tracks subagent lifecycle via SDK hooks and keeps the session alive until all team members finish, then prompts the lead agent to synthesize results.
How it works:
- You submit a prompt that describes a multi-part task
- Claude spawns subagents via the
Tasktool, each working on a portion concurrently - Gluon's
SubagentTrackermonitors start/stop events to know when team members finish - The lead agent synthesizes results from all subagents into a cohesive output
Enable globally via the web dashboard settings, or per-task via the API:
# 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:
Refactor the authentication module:
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 opusfor 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.
Browser Automation & Screenshots
- agent-browser - Pre-installed Chromium for headless browser automation (open, click, type, screenshot)
- Screenshot Interception - Screenshots captured via
agent-browser screenshotare 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
Additional Features
- Image Attachments - Paste screenshots/diagrams for AI context (Cmd+V in resume prompt)
- Usage Tracking - Monitor costs, tokens, and usage per project
- Docker Deployment - Full containerized deployment with docker-compose
- CI/CD Workflows - GitHub Actions for CI and Docker image publishing
- Log Persistence - Stdout, stderr, and structured message logs for every run
- Mobile Optimized - iOS Safari zoom prevention, touch-friendly interactions
- Context Overflow Recovery - Automatic recovery when agent exceeds context window (
gluon recover) - Log Cleanup - Retention-based cleanup of old log files (
gluon cleanup) - Disk Stats - Monitor
~/.gluondisk usage (gluon stats)
Web Dashboard (docs · API)
gluon web
# Open http://localhost:45866
The dashboard provides:
| View | Description |
|---|---|
| Kanban Board | Queue → Running → Review → Done columns with drag-and-drop |
| Activity Feed | Cross-agent event stream (run completions, PRs, merges) |
| Work Queue | Batch and schedule tasks across projects |
| Merge Queue | Sequential PR merge processing with conflict status |
| Settings | Configure models, blueprints, agent teams, and more |
Run Details include:
- Live message stream with tool call visualization
- Git commits and file diffs
- Image attachments and browser screenshots
- Cost and token usage tracking
- Formula step progress (for multi-step workflows)
- One-click PR creation and merge
- Witness health classification
Chat Bots (Telegram · Discord)
Telegram
export GLUON_TELEGRAM_TOKEN="your-bot-token"
export GLUON_TELEGRAM_USERS="123456789" # Allowed user IDs
gluon bot
Discord
export GLUON_DISCORD_TOKEN="your-bot-token"
export GLUON_DISCORD_GUILD="your-guild-id"
gluon discord
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"
Architecture (docs)
graph TB
subgraph Interfaces
CLI[CLI]
WEB[Web Dashboard]
TG[Telegram Bot]
DC[Discord Bot]
WH[Webhooks]
end
subgraph Core
ORCH[Orchestrator Agent]
RUNNER[Task Runner Agent]
end
subgraph Workers [Execution Workers]
subgraph Worker1 [Worker 1 - Local]
AGENT1[Gluon Agent]
SDK1[Claude Agent SDK]
CLAUDE1[Claude CLI]
end
subgraph WorkerN [Worker n - Remote]
AGENTN[Gluon Agent]
SDKN[Claude Agent SDK]
CLAUDEN[Claude CLI]
end
end
subgraph Services
STORE[(SQLite)]
GIT[Git Manager Agent]
EBUS[Event Bus]
REDIS[Redis Pub/Sub]
end
CLI --> ORCH
WEB --> ORCH
TG --> ORCH
DC --> ORCH
WH --> ORCH
ORCH --> RUNNER
ORCH --> GIT
RUNNER --> STORE
RUNNER --> GIT
RUNNER --> AGENT1
RUNNER -.-> AGENTN
RUNNER --> EBUS
EBUS --> REDIS
REDIS --> WEB
AGENT1 --> SDK1
SDK1 --> CLAUDE1
AGENTN --> SDKN
SDKN --> CLAUDEN
Model Selection
| Model | Best For | Flag |
|---|---|---|
| Haiku 4.5 | Quick fixes, simple tasks | --model haiku |
| Sonnet 4.6 | Most coding tasks | --model sonnet |
| Opus 4.6 | Complex refactoring | --model opus-4.6 |
| Opus 4.7 | Complex refactoring, architecture | --model opus-4.7 |
| Opus 4.8 | Complex refactoring, architecture (latest, default) | --model opus |
gluon run myapp 'Fix typo' --model haiku
gluon run myapp 'Implement OAuth' --model sonnet
gluon run myapp 'Redesign database schema' --model opus
Documentation
| Document | Description |
|---|---|
| Changelog | Release history and notable changes |
| CLI Reference | Complete CLI command reference |
| Authentication | Multi-user auth model — local + OIDC + RBAC + attribution + transport linking |
| OIDC Setup | Provider-specific recipes (Auth0, Google, Cognito, Entra) |
| LLM Provider Guide | Bedrock / Anthropic / Vertex / Foundry configuration |
| Web Dashboard | Dashboard features and API |
| Ralph Loop | Autonomous execution mode and supervision |
| Agent Teams | Claude Code multi-agent coordination (external) |
| Git Operations | Worktrees, PR integration, conflict resolution |
| Telegram Bot | Telegram setup and commands |
| Discord Bot | Discord setup and commands |
| Docker | Container deployment |
| Architecture | System architecture and data models |
| API Reference | REST and WebSocket API |
| Screenshots | Web UI and mobile PWA gallery |
| Development | Contributing and extending |
Data Storage
~/.gluon/
├── gluon.db # SQLite database
├── images/ # Image attachments
└── logs/ # Per-run logs
└── <run_id>/
├── stdout.log
├── stderr.log
└── messages.jsonl
Environment Variables
LLM Provider
| Variable | Description |
|---|---|
GLUON_LLM_PROVIDER | Provider name: bedrock (default), anthropic, vertex, or foundry |
ANTHROPIC_MODEL | Override model for all runs |
ANTHROPIC_DEFAULT_OPUS_MODEL | Pin a specific Opus version for third-party deployments |
ANTHROPIC_DEFAULT_SONNET_MODEL | Pin a specific Sonnet version |
ANTHROPIC_DEFAULT_HAIKU_MODEL | Pin a specific Haiku version |
Bedrock — AWS_REGION, AWS_BEARER_TOKEN_BEDROCK (or standard AWS creds), ANTHROPIC_BEDROCK_BASE_URL (optional gateway).
Anthropic Direct — ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL (optional). Or use claude login for a CLI session.
Google Vertex AI — ANTHROPIC_VERTEX_PROJECT_ID, CLOUD_ML_REGION (e.g. global / us-east5), GOOGLE_APPLICATION_CREDENTIALS (optional), ANTHROPIC_VERTEX_BASE_URL (optional gateway).
Microsoft Foundry — ANTHROPIC_FOUNDRY_RESOURCE (or ANTHROPIC_FOUNDRY_BASE_URL), ANTHROPIC_FOUNDRY_API_KEY (or Entra ID via az login).
See docs/LLM-PROVIDER.md for the full reference.
Bot Configuration
| Variable | Description |
|---|---|
GLUON_TELEGRAM_TOKEN | Telegram bot token |
GLUON_TELEGRAM_USERS | Allowed Telegram user IDs (comma-separated) |
GLUON_DISCORD_TOKEN | Discord bot token |
GLUON_DISCORD_GUILD | Discord guild (server) ID |
GLUON_DISCORD_USERS | Allowed Discord user IDs (comma-separated) |
Multi-User Auth (Optional · default off · full guide)
| Variable | Default | Description |
|---|---|---|
GLUON_AUTH_ENABLED | false | Master switch. When false, no login UI and no role checks — single-user install. |
GLUON_LOCAL_AUTH_ENABLED | true | Set false to disable the password endpoint (OIDC-only mode). |
GLUON_AUTH_SWEEP_INTERVAL_SECS | 3600 | How often the periodic task sweeps expired sessions and unconsumed link codes. |
GLUON_OIDC_ISSUER | (unset) | OIDC discovery URL, e.g. https://accounts.google.com. Setting this + the next 3 vars enables OIDC. |
GLUON_OIDC_CLIENT_ID | (unset) | Client ID from your IdP's app registration. |
GLUON_OIDC_CLIENT_SECRET | (unset) | Client secret. Never commit. |
GLUON_OIDC_REDIRECT_URI | (unset) | Must match what's registered with the IdP, e.g. https://gluon.example.com/api/auth/oidc/callback. |
GLUON_OIDC_PROVIDER_NAME | OIDC | Display name on the login button. |
GLUON_OIDC_AUTO_PROVISION | false | Auto-create new users on first login. Requires GLUON_OIDC_DOMAIN_ALLOWLIST. |
GLUON_OIDC_DOMAIN_ALLOWLIST | (unset) | Comma-separated email-domain allowlist. Required when auto-provision is on. |
GLUON_OIDC_DEFAULT_ROLE | viewer | Role assigned to auto-provisioned users. |
See docs/AUTH-OIDC.md for provider-specific recipes (Auth0, Google Workspace, AWS Cognito, Microsoft Entra ID).
Docker-Specific
| Variable | Description |
|---|---|
PUID | Host user UID — container runs as this user (default 1000, find with id -u) |
PGID | Host group GID — container runs as this group (default 1000, find with id -g) |
GH_TOKEN | GitHub token for HTTPS authentication (replaces SSH) |
GIT_USER_NAME | Git commit author name |
GIT_USER_EMAIL | Git commit author email |
VERCEL_TOKEN | Vercel API token (optional, used as fallback when not set in Settings UI) |
Remote Access
Run Gluon on a home server (e.g., Mac mini) and access it securely from anywhere using Tailscale, a zero-config VPN:
- Install Tailscale on your server and devices
- Start Gluon:
gluon webordocker compose up -d - Access the dashboard from any device via your Tailscale IP:
http://your-server:45866
This enables monitoring and managing AI coding tasks from your phone, tablet, or laptop while on the go - with the PWA providing a native app-like experience on mobile.
Credits & Inspiration
I was an early user of Vibe Kanban (https://www.vibekanban.com) and was inspired by the concept of a Kanban board for AI-assisted development. I wanted to create a similar experience for Gluon, but with a focus on multi-project orchestration.
License
MIT License - see LICENSE for details.
Contributing (docs)
Contributions are welcome! Please read DEVELOPMENT.md for guidelines.