Install Takuto Core

This is the build-your-own-container path: clone the Takuto Core engine, edit config.toml, and run it with Docker Compose directly. Choose this when you want full control over the image, the deployment, and the network in front of it.

Just want to try it quickly on one project? The Takuto CLI generates these files and runs Compose for you. Both paths run the same engine.

Prerequisites

See Overview → Prerequisites. In short: Docker (or Podman) with docker compose, ≥ 8 GiB RAM, ≥ 30 GiB free disk, a GitHub token, and an AI provider account.

Individual developer (local)

Run Takuto Core on your laptop. Plan for fifteen to twenty minutes, since this path builds the container image locally.

1. Clone and configure

git clone https://github.com/takuto-team/takuto-core && cd maestro-core
cp config.toml.example config.toml
cp takuto.env.example takuto.env

Edit config.toml:

  • Set [general] ticketing_system to "jira", "github", or "none".
  • For Jira: fill in [jira] site, project_keys, and email.
  • For GitHub Issues: the repo is detected from the cloned repository’s git remote.

Put secrets in takuto.env (never in config.toml):

export ANTHROPIC_API_KEY="sk-ant-..."
export GH_TOKEN="github_pat_..."

2. Build

docker compose build

3. Authenticate (first time only)

docker compose run --rm -it takuto setup

This walks you through GitHub CLI → Atlassian CLI (optional) → Claude Code or Cursor Agent → cloning your repository.

Podman on macOS: increase the VM’s resources first:

podman machine stop && podman machine set --memory 12288 --cpus 4 && podman machine start

4. Start

docker compose up

The dashboard is at http://localhost:8080. On first boot, create the initial admin account. If you use Jira or GitHub Issues, polling starts automatically; otherwise click + to start a workflow manually.

Team deployment (server)

Self-host Takuto Core on a Linux server. Your team uses the dashboard through a browser; the agent runs in the background.

1. Clone and configure on the server

git clone https://github.com/takuto-team/takuto-core && cd maestro-core
cp config.toml.example config.toml
cp takuto.env.example takuto.env

Key settings for a shared deployment:

[general]
ticketing_system = "jira"          # or "github"
max_concurrent_workflows = 3       # tune to your server's CPU/RAM

[web]
host = "0.0.0.0"
port = 8080

Takuto Core uses a multi-user database for authentication. On first boot the dashboard prompts you to create the initial admin account; that admin can then create additional users from Configuration → Users.

2. Build and authenticate

docker compose build
docker compose run --rm -it takuto setup

3. Start as a service

docker compose up -d

Takuto Core listens on plain HTTP. Terminate TLS in front of it with nginx or Caddy pointed at port 8080.

Example Caddy snippet:

takuto.yourcompany.com {
    reverse_proxy localhost:8080
}

When behind a TLS terminator, set the dashboard’s allowed origins so cookies and CORS work correctly:

[web]
cors_origins = ["https://takuto.yourcompany.com"]

cookie_secure auto-detects HTTPS from cors_origins or an inbound X-Forwarded-Proto: https header; force it true if your proxy does not send that header. See the Configuration reference for the full [web] table.

Multi-user model

Takuto Core is multi-user, single-tenant: every user has their own dashboard view, but all users on one instance share the same Jira, GitHub, and AI credentials.

  • admin — can create, edit, suspend, and delete users, and change shared settings (polling, concurrency, workspace switch, repo clone).
  • user — sees and acts only on workflows they created. No cross-user visibility, even for admins.

Sign-in is username + password (argon2-hashed). Sessions have a 24-hour idle TTL and a 30-day absolute TTL; accounts lock after 5 failed attempts in 10 minutes. One-time recovery codes issued at account creation can reset a forgotten password.

Anyone you give an account to can run code in worker containers under the deployment’s identity — including the tokens in takuto.env. Do not grant accounts to people you do not trust.

Persistence across restarts

All auth state (GitHub, Atlassian, Claude/Cursor), workflow snapshots, and the npm cache live in named Docker volumes. Workflows survive docker compose restart — paused or in-progress runs resume automatically.

Optional sidecars

  • Docker-in-Docker — merge docker-compose.dind.yml to run each workflow’s steps in ephemeral Docker containers (prevents port and filesystem conflicts between concurrent workflows). See Extending Takuto Core.
  • Self-hosted model bridge — merge docker-compose.lm-bridge.yml when you point the OpenCode provider at a model server running on the host Mac. See Self-hosted models.

Next steps