convez.ai
AgenteDevOps & InfraestruturaAvançado
carrotly-ai

Gluon Agent

carrotly-ai/gluon-agent

Orquestrador multi-cloud para agentes Claude Code em Docker com dashboard e controle remoto

Ver no GitHub
BomPluginScore · de 0 a 100

Orquestrador 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-agent

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
11
Forks
0
Acompanhando
0
Saúde
37%
Último commit
há 4 dias
Versão
v0.12.1
Issues abertas
15
Contribuidores
4

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

License: MIT Python 3.12+

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.

Kanban board

Task review

See all screenshots in docs/SCREENSHOTS.md

Table of Contents

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

GluonClaude DeckclaudectlKingCoding
Self-hosted✅✅✅❌
Multi-cloud LLM backend (Bedrock + Vertex + Foundry + direct)✅❌❌❌
Multi-transport (CLI+TG+Discord+Web)✅Web onlyCLI onlyMobile 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:

ProviderCredentials
AWS Bedrock (default)~/.aws (mounted read-only)
Anthropic DirectANTHROPIC_API_KEY env var or ~/.claude login
Google Vertex AI~/.config/gcloud (run gcloud auth application-default login)
Microsoft Foundry~/.azure (run az login) or ANTHROPIC_FOUNDRY_API_KEY env 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_TOKEN for GitHub access (no SSH keys needed)
  • MCP Server Auto-Registration - Mount .mcp.json to auto-register MCP servers on startup
  • Pre-built Image - ghcr.io/carrotly-ai/gluon-agent:latest updated on every push to main

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.

BackendModel ID schemeCredentials
AWS Bedrock (default)global.anthropic.claude-sonnet-4-6AWS env or ~/.aws
Anthropic Directclaude-sonnet-4-6ANTHROPIC_API_KEY or claude login
Google Vertex AIclaude-sonnet-4-6 / claude-haiku-4-5@20251001GCP ADC (gcloud auth application-default login)
Microsoft Foundryclaude-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 doctor command 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-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 · 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, 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.

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 opus in 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:

FormulaStepsDescription
featurePlan → Implement → Test → ReviewFull feature development lifecycle
bugfixDiagnose → Fix → TestBug 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:

  1. The first step creates an ExecutionRun in a git worktree
  2. Subsequent steps resume the same run with fresh_session=True — new Claude session, same worktree
  3. The Kanban board shows a single card with a step progress bar (e.g., "Step 2/4 Implement")
  4. 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):

  1. Auto-fix — Runs the project's linter with auto-fix (e.g., ruff check --fix && ruff format .)
  2. Lint loop — If lint errors remain, the agent is resumed to fix them (up to 3 attempts)
  3. 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:

ClassificationMeaning
healthyNormal progress
slowBelow expected throughput
loopingRepeating similar actions
stuckNo meaningful progress
zombieProcess 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:

  1. You submit a prompt that describes a multi-part task
  2. Claude spawns subagents via the Task tool, each working on a portion concurrently
  3. Gluon's SubagentTracker monitors start/stop events to know when team members finish
  4. 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 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.

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

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 ~/.gluon disk usage (gluon stats)

Web Dashboard (docs · API)

gluon web
# Open http://localhost:45866

The dashboard provides:

ViewDescription
Kanban BoardQueue → Running → Review → Done columns with drag-and-drop
Activity FeedCross-agent event stream (run completions, PRs, merges)
Work QueueBatch and schedule tasks across projects
Merge QueueSequential PR merge processing with conflict status
SettingsConfigure 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

ModelBest ForFlag
Haiku 4.5Quick fixes, simple tasks--model haiku
Sonnet 4.6Most coding tasks--model sonnet
Opus 4.6Complex refactoring--model opus-4.6
Opus 4.7Complex refactoring, architecture--model opus-4.7
Opus 4.8Complex 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

DocumentDescription
ChangelogRelease history and notable changes
CLI ReferenceComplete CLI command reference
AuthenticationMulti-user auth model — local + OIDC + RBAC + attribution + transport linking
OIDC SetupProvider-specific recipes (Auth0, Google, Cognito, Entra)
LLM Provider GuideBedrock / Anthropic / Vertex / Foundry configuration
Web DashboardDashboard features and API
Ralph LoopAutonomous execution mode and supervision
Agent TeamsClaude Code multi-agent coordination (external)
Git OperationsWorktrees, PR integration, conflict resolution
Telegram BotTelegram setup and commands
Discord BotDiscord setup and commands
DockerContainer deployment
ArchitectureSystem architecture and data models
API ReferenceREST and WebSocket API
ScreenshotsWeb UI and mobile PWA gallery
DevelopmentContributing 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

VariableDescription
GLUON_LLM_PROVIDERProvider name: bedrock (default), anthropic, vertex, or foundry
ANTHROPIC_MODELOverride model for all runs
ANTHROPIC_DEFAULT_OPUS_MODELPin a specific Opus version for third-party deployments
ANTHROPIC_DEFAULT_SONNET_MODELPin a specific Sonnet version
ANTHROPIC_DEFAULT_HAIKU_MODELPin 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

VariableDescription
GLUON_TELEGRAM_TOKENTelegram bot token
GLUON_TELEGRAM_USERSAllowed Telegram user IDs (comma-separated)
GLUON_DISCORD_TOKENDiscord bot token
GLUON_DISCORD_GUILDDiscord guild (server) ID
GLUON_DISCORD_USERSAllowed Discord user IDs (comma-separated)

Multi-User Auth (Optional · default off · full guide)

VariableDefaultDescription
GLUON_AUTH_ENABLEDfalseMaster switch. When false, no login UI and no role checks — single-user install.
GLUON_LOCAL_AUTH_ENABLEDtrueSet false to disable the password endpoint (OIDC-only mode).
GLUON_AUTH_SWEEP_INTERVAL_SECS3600How 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_NAMEOIDCDisplay name on the login button.
GLUON_OIDC_AUTO_PROVISIONfalseAuto-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_ROLEviewerRole assigned to auto-provisioned users.

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

Docker-Specific

VariableDescription
PUIDHost user UID — container runs as this user (default 1000, find with id -u)
PGIDHost group GID — container runs as this group (default 1000, find with id -g)
GH_TOKENGitHub token for HTTPS authentication (replaces SSH)
GIT_USER_NAMEGit commit author name
GIT_USER_EMAILGit commit author email
VERCEL_TOKENVercel 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:

  1. Install Tailscale on your server and devices
  2. Start Gluon: gluon web or docker compose up -d
  3. 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.

Ver o original no GitHub

Bom para

Relacionados