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.

Provider testing status (beta). Claude Code was last verified before Anthropic made an API key mandatory for its headless mode, and Codex has not been tested yet. They should still work, but you may hit rough edges. If you do, let us know — feedback is very welcome and helps us fix any issue quickly.

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 for Claude Code (its headless mode now requires an API key), 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) — your own Atlassian API token. Each user adds their own token in the dashboard (Configuration → Ticketing); reads and writes then act as you. A deployment-wide owner token is only a fallback for users who haven’t added one.

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

2. Install the CLI

Homebrew (recommended):

brew install takuto-team/tap/takuto

Or grab the binary directly:

# Apple Silicon (arm64) — Intel is takuto-darwin-amd64
curl -L -o takuto https://github.com/takuto-team/takuto-cli/releases/latest/download/takuto-darwin-arm64
chmod +x takuto && sudo mv takuto /usr/local/bin/

Homebrew (recommended):

brew install takuto-team/tap/takuto

Or grab the binary directly:

# amd64 — arm64 is takuto-linux-arm64
curl -L -o takuto https://github.com/takuto-team/takuto-cli/releases/latest/download/takuto-linux-amd64
chmod +x takuto && sudo mv takuto /usr/local/bin/

Download the binary and add it to your PATH. In PowerShell:

# Download the latest Windows binary
curl.exe -L -o takuto.exe https://github.com/takuto-team/takuto-cli/releases/latest/download/takuto-windows-amd64.exe
# Then move takuto.exe into a folder that's on your PATH (e.g. a tools directory)

Inside WSL you’re in a Linux environment, so install it the Linux way. Make sure Docker (e.g. Docker Desktop with WSL integration) is reachable from your WSL distro.

Homebrew (recommended):

brew install takuto-team/tap/takuto

Or grab the binary directly:

# amd64 — arm64 is takuto-linux-arm64
curl -L -o takuto https://github.com/takuto-team/takuto-cli/releases/latest/download/takuto-linux-amd64
chmod +x takuto && sudo mv takuto /usr/local/bin/

For all binaries and checksums, 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. Finish in the dashboard

On first boot the dashboard walks you through a short setup wizard, in order:

  1. GitHub — your PAT, or a GitHub App for bot-attributed commits and PRs.
  2. Repositories — clone the repo(s) you want Takuto to work on.
  3. AI provider — your provider key (ANTHROPIC_API_KEY, CURSOR_API_KEY, OPENAI_API_KEY…), or a self-hosted endpoint.
  4. Ticketing — Jira or GitHub Issues, plus per-repository polling (project keys, item types, filters) set for each repo. Each user adds their own Jira token here.
  5. Workflows — review the seeded TOML pipelines.

Existing values pre-fill their fields (secrets show a •••••• placeholder); you can also put secrets in .takuto/takuto.env before starting (see Configuration). Once a repository and ticketing are set, polling starts automatically and picks up “To Do” tickets — or click + to paste a description and start 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.