Documentation.

Quick start

The documented setup path is a source checkout plus the open-source startup target.

git clone https://github.com/agent-starbase/agent-starbase.git
cd agent-starbase
make start-open-source
open https://localhost:6886

This path expects Docker, Docker Compose, make, and Ruby 3.2+. The first run initializes local config, generates secrets, builds missing images, runs migrations, starts the web UI, and checks the DinD/runtime services.

Optional agent installs

The default open-source image ships with Codex. Add optional local vendor tools only after reviewing their license and service terms.

make install-claude        # Claude Code path
make install-agents        # interactive optional-agent installer
make start-local-proprietary

Build modes

Pick one before your first build.

Open-source path

Use this for the redistributable build. It starts the documented open-source stack with Codex included and no Anthropic key required.

make start-open-source

User-built proprietary extension

Open-source base plus locally installed vendor tools such as Claude Code, Gemini, Copilot, OpenCode, Pi, Cline, Continue, Grok Build, LLM, DeepAgents, Browser Use, OpenHands, and Bash. Review each vendor's license and service terms before installing.

make install-claude
make install-agents
make start-local-proprietary

Update agents

For the open-source stack, rebuild the agent image and swap containers:

make rebuild-agent-open-source

Optional local vendors

For optional local vendor tools added with make install-claude or make install-agents, reinstall using those installers and then rebuild:

make install-claude        # if Claude path changed
make install-agents         # interactive optional-agent installer
make rebuild-agent-local-proprietary

Your first job

1. Log in at https://localhost:6886 with the generated admin password in .env.
2. Clone a project under the workspace/ folder in Agent Starbase.
3. Pick an agent and the created working directory.
4. Write a prompt, attach images or files if needed, then start the job.
5. Open the live terminal with the Console button, review the diff with the Git Commit button, and approve commits from the UI.

Architecture

Every agent runs in its own container, reachable only through a controlled egress path.

Browser (Web UI)
       │
       ▼
┌──────────────────────────────────┐
│  Agent Container                 │
│  • Runs as non-root user         │
│  • iptables blocks direct egress │
│  • Setuid binaries removed       │
│  • 1 CPU / 8 GB RAM default      │
└──────────────┬───────────────────┘
               │ all traffic forced through proxy
               ▼
┌──────────────────────────────────┐
│  Proxy Container (Squid)         │
│  • Enforces domain whitelist     │
│  • Logs every request            │
│  • Hot-swappable filter modes    │
└──────────────┬───────────────────┘
               ▼
         Internet (filtered)

Supporting containers: PostgreSQL (job persistence), Nginx (HTTPS/SSL), and a git helper for SSH-isolated git operations.

Security model

• No default credentials — passwords are generated on first startup.
• Non-root agents — agents never run as root; setuid binaries are removed from the image.
• Kernel-level egress block — iptables rules prevent direct outbound traffic.
• Proxy whitelist — Squid only lets approved domains through and logs everything.
• Resource caps — defaults are 1 CPU, 8 GB RAM, and 3072 PIDs per agent container, configurable through environment variables.
• Audit logs on host — structured agent logs written to ./data/agent-logs/, outside the container.