Quick start

The canonical “try it now” path: install the Takuto CLI, run takuto setup then takuto start, and finish in the dashboard. It takes a few minutes.

Recommended setup. A few choices make for the smoothest, most production-ready run:

  • Authenticate GitHub with a GitHub App, not a personal access token (PAT). PRs are then opened under a dedicated bot identity instead of your personal account — cleaner authorship, and access stays scoped to what the app grants.
  • Protect the branches the agent targets. An autonomous agent can do anything its token allows, so enable branch protection on main (and any target branch): require a PR before merging, require an approving review, and forbid direct pushes. Paired with a bot identity, this gives you a mandatory review gate even when you work solo.
  • Use an external database (Postgres / MySQL / MariaDB) so your data lives outside the container and can be backed up.

Everything below works without these, but they are worth setting up early.

Prefer to run the engine yourself without the CLI? See Install Takuto Core for the build-your-own-container path.

1. Create the tokens you’ll need

Have these ready before you start — you’ll add them in the dashboard (step 6):

  • An AI provider credential — one of: an Anthropic API key (or a Claude Pro/Max login) for Claude Code, an OpenAI API key for Codex, a Cursor API key for Cursor Agent — or none if you run a self-hosted model through OpenCode.
  • GitHub access — a fine-grained personal access token scoped to the repos Takuto will work on (Contents and Pull requests: read & write; Metadata: read; Issues: read & write if you poll GitHub Issues). Better still, set up a GitHub App so PRs come from a scoped bot identity rather than your personal account.
  • Jira (only if you’ll poll Jira) — an Atlassian API token for the account Takuto should act as.

Scope every token to the minimum it needs — these bound what an autonomous agent can reach.

2. Install the CLI

Homebrew (macOS / Linux — recommended):

brew install takuto-team/tap/takuto

For manual binary downloads (including Windows), see the Releases page and the CLI reference.

3. Prerequisites

All you need installed is Docker or Podman — the CLI auto-detects which one you have.

You don’t pull the Takuto Core image yourself: takuto start pulls it on first run (and falls back to a cached copy if you’re offline). It’s published publicly, so no registry authentication is needed — though you can pre-pull it manually with docker pull ghcr.io/takuto-team/takuto-core:latest if you prefer.

4. Generate your config

takuto setup

The wizard is short: now that the dashboard handles most configuration, it only asks for the dashboard port and — if you use an external database (Postgres / MySQL / MariaDB) — its connection details (otherwise it defaults to the built-in SQLite). Everything else — ticketing system, AI provider and models, polling, workflows — is set up later in the dashboard. It generates takuto.yml plus a .takuto/ folder with config.toml, secrets (takuto.env), and a workflows/ folder of starter pipeline definitions:

takuto.yml                  # Docker Compose orchestration
.takuto/
  config.toml                # bootstrap configuration
  takuto.env                # secrets and API tokens
  workflows/                 # pipeline step definitions
    implement_ticket.toml
    merge_base.toml
    address_pr_comments.toml

The .takuto/ folder is created wherever you run the command — it does not have to be a project directory. Run takuto setup/takuto start from different folders to keep multiple isolated Takuto instances side by side: each gets its own config, authentication, workspaces, and database, with no extra configuration needed.

Pointing at an external database — especially one running in a container? Getting the connection string right is the one tricky part: see External database.

5. Start Takuto

takuto start

Then open the dashboard in your browser — http://localhost:8080 by default, or the port you chose during takuto setup. takuto start pulls the image (first run) and brings up the stack. On first boot the dashboard prompts you to create the initial admin account.

6. Authenticate and add a project

Add the tokens from step 1, then point Takuto at a repository:

  • Recommended — the tokens from step 1: enter your provider key and GitHub token (ANTHROPIC_API_KEY, CURSOR_API_KEY, OPENAI_API_KEY, scoped GH_TOKEN…) from the dashboard’s Configuration screens, or put them in .takuto/takuto.env before starting (see Configuration).
  • Click “Setup a New Project” in the dashboard to clone the repository you want Takuto to work on.
  • If you configured Jira or GitHub Issues, polling starts automatically and picks up “To Do” tickets. Otherwise click + to paste a description and kick off a workflow manually.

Optional — takuto auth (not recommended). takuto auth runs interactive OAuth logins (GitHub + your AI provider) from the CLI. OAuth grants broad account access, so we recommend scoped API keys/tokens (above) instead. Use takuto auth only if you specifically need the interactive login flow.

What happens next

Each workflow creates a git worktree from your base branch, runs your worktree-init commands (e.g. npm ci), then runs the agent steps from your TOML workflow definition. Watch the live terminal output on each workflow card, and open a browser-based VS Code editor on any worktree with Open editor.

See How it works for the full workflow lifecycle, and the CLI reference for stop, restart, and multi-project isolation.

Stop and restart

takuto stop       # stop Takuto services
takuto restart    # restart Takuto services

All authentication state, workflow snapshots, and caches live in named Docker volumes, so workflows survive a restart — paused or in-progress runs resume automatically.