Setup Guide
Detailed configuration reference for Toban Projects, agents, repositories, and the CLI.
Prerequisites
- Node.js 20+
- A GitHub account (for OAuth login)
- Claude Code CLI:
npm install -g @anthropic-ai/claude-code
GitHub App and OAuth
Toban uses two GitHub integrations:
GitHub OAuth App
Used for user authentication. When you sign in at toban.dev, you authorize Toban to read your GitHub identity. This creates a session cookie used by the dashboard.
GitHub App
Used for repository operations. The GitHub App is installed on your organization or personal account and grants Toban:
- Read access to repository metadata
- Write access for creating branches and pushing commits
- Token generation for git operations (installation tokens, 1hr expiry)
When you connect a repository during Project setup, Toban checks that the GitHub App is installed with access to that repository. If not, it prompts you to install or reconfigure the App.
Project Creation
The setup wizard collects all configuration before creating anything. The Project is deferred -- it is only created in the database after you complete the final step. This prevents orphaned Projects if you abandon the wizard.
Wizard Steps
- Project name and description -- Display name for the Project
- GitHub repository -- The primary repo agents will work on
- Agent engine -- Currently Claude Code is the only production-ready engine
- Confirmation -- Review and create
After creation, you land on the Sprint page. The next steps are:
- Write your project spec at
/spec - Add additional repositories at Settings > Repositories
Repository Configuration
Main Repository
Set during Project creation. This is the primary codebase that agents clone and work on. The repository URL is stored as github_repo (format: owner/repo).
Sub Repositories
Additional repositories can be registered at Settings > Repositories. Each entry has:
| Field | Description |
|---|---|
repo_name |
Display name |
repo_path |
GitHub path (owner/repo) or local path |
description |
Optional description |
access_agents |
Which agent roles can access this repo (empty = all) |
The CLI clones all registered repositories at startup and creates worktrees in the appropriate repo for each task.
Access Control
By default, all agents can access all repositories. To restrict access:
- Go to Settings > Repositories
- Edit the repository
- Add specific agent roles to the access list (e.g., only
builder)
Agent Configuration
Engine Selection
Each agent has an engine configuration that determines how it runs:
| Setting | Description |
|---|---|
engine |
Engine type: claude-code (recommended), claude-api, gemini, codex, custom |
execution_mode |
Currently local only (BYOK mode is not yet functional) |
command_template |
Custom command template for the custom engine |
Configure agents at the Agents page or via PUT /api/v1/agents/:name/config.
Agent Roles
| Role | Capabilities |
|---|---|
| Manager | Sprint coordination, task proposals, chat interaction (read-only repo access) |
| Builder | Full code read/write, test execution, commits |
The Manager is created automatically during Project setup. The Builder is the primary worker agent.
Sprint Configuration
Creating a Sprint
Sprints can be created from the dashboard Sprint page or via the API:
POST /api/v1/sprints
{ "number": 1 }Sprint Status
Sprints start as Active by default -- there is no planning phase in the UI. The planning status exists in the API for backward compatibility but is not used in the current UX. The phase flow is: Active -> Review -> Retrospective -> Completed.
Manager Interaction
The Manager is an LLM-powered agent that coordinates the sprint. It:
- Proposes tasks based on the project spec and backlog
- Responds to user chat messages
- Requests approval before spawning worker agents
- Tracks task progress and suggests status transitions
The Manager uses the enriched context from GET /api/v1/manager/context, which includes tasks, agent statuses, the project spec, backlog items, and retrospective data from previous sprints.
CLI Configuration
Environment Variables
| Variable | Required | Description |
|---|---|---|
TOBAN_API_URL |
Yes | Toban API base URL |
TOBAN_API_KEY |
Yes | Project API key |
LLM_BASE_URL |
No | OpenAI-compatible API URL for Manager (overrides Claude CLI) |
LLM_API_KEY |
No | API key for the LLM provider |
DEBUG |
No | Set to 1 for verbose output |
CLI Flags
All environment variables can be overridden with CLI flags:
npx toban-cli@latest start \
--api-url https://api.toban.dev \
--api-key tb_wsXXX_sk_XXX \
--working-dir /path/to/your/repo \
--branch main \
--model claude-sonnet-4-20250514 \
--ws-port 4000WebSocket Port
The CLI starts a WebSocket server (default port 4000) that the Dashboard connects to for real-time communication. If port 4000 is unavailable, use --ws-port 0 for automatic port selection. The CLI registers its port with the API so the Dashboard can discover it.
Project Settings
| Setting | Description |
|---|---|
name |
Project display name |
description |
Project description |
language |
AI communication language (en or ja) |
workflow |
Workflow type: scrum, kanban, or checklist |
github_repo |
Connected GitHub repository (owner/repo) |
spec |
Project specification (editable at /spec) |
terminal_emulator |
Preferred terminal for local agent execution |
Update via the Settings page or PUT /api/v1/workspace (the API uses workspace internally).
Backend Deployment
Cloudflare Workers (API)
The API runs on Cloudflare Workers with D1 (SQLite) storage.
cd toban/api
npm install
# Configure wrangler.jsonc with your Cloudflare account
# Set secrets:
# GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET
# GITHUB_APP_ID, GITHUB_PRIVATE_KEY
# APP_URL (frontend URL for OAuth redirect)
# Run migrations
npx wrangler d1 migrations apply toban-db
# Deploy
npm run deployFrontend (Next.js)
The dashboard is a Next.js application deployed to any Node.js hosting platform.
cd toban
npm install
# Create .env.local:
# API_URL=https://your-api.example.com
# API_KEY=internal-proxy-key
npm run build
npm run startInfrastructure (Terraform)
The terraform/ directory manages Cloudflare resources:
- D1 database
- Workers deployment
- Custom domain configuration
- Monitoring and alerting