Frequently asked questions

Can I use Takuto freely?

Yes. Self-hosting Takuto Core for your own use — on your machine or inside your company — is free: no fees to the project, no seat limits, no usage caps it imposes on you. The engine is source-available under the FSL-1.1-ALv2 and the Takuto CLI is MIT, so you are free to run, modify, and self-host it for any non-competing purpose. There is no telemetry and nothing phones home.

The one limit worth knowing: the FSL forbids competing use — you can’t use Takuto Core to offer a competing product or hosted service. Internal use, evaluation, and client work via professional services are fine, and each version converts to Apache-2.0 two years after release. If those terms don’t fit, get in touch.

What does it cost to run?

Takuto Core itself doesn’t bill you — your AI provider does. The agent runs Claude Code, Cursor Agent, Codex, or a self-hosted model against your account, and each ticket consumes tokens proportional to the codebase size, the prompt context, and the number of steps in your workflow. What that costs depends entirely on the provider and model you choose, so check their current rates — and watch your first few runs to get a feel for your own workload.

Cost-saving levers:

  • Use command steps for deterministic work (lint, test) — they consume no AI tokens.
  • Cap context with [jira] ticket_context_max_description_bytes.
  • Rehearse with [general] dry_mode = true before pointing at a real backlog.
  • A self-hosted model via OpenCode removes per-token billing entirely (you pay only for the hardware) — see Self-hosted models.

Is it production-ready?

Takuto Core is in beta. It is usable today, and people are running real workflows with it — but expect rough edges, and all feedback is welcome. Beta status is also why the messaging across this site leans toward “try it, tell us what breaks” rather than “enterprise-ready”. Every report helps shape where the project goes next.

Can I contribute? Why aren’t pull requests accepted?

Takuto Core is source-available, but the author does not accept pull requests for now. This is a deliberate, temporary stance for legal reasons: the project needs time to be observed and structured properly — contributor licensing, governance, and trademark all need to be in place before outside code can be merged responsibly.

That does not mean feedback is unwelcome — quite the opposite. Bug reports, feature requests, and general feedback are very much wanted. Open an issue or reach out at morphet.contact@gmail.com. The restriction is specifically on merging external code, not on the conversation around the project.

What are the licenses?

Two components, two licenses:

  • Takuto Core (the engine you self-host) is source-available under the Functional Source License 1.1 (FSL-1.1-ALv2): free for any non-competing use, and each version converts to Apache-2.0 two years after release. You may not use it to offer a competing product or hosted service. If those terms don’t fit, reach out at morphet.contact@gmail.com — happy to discuss.
  • The Takuto CLI (the companion setup tool) is licensed under MIT.

The Takuto Core source is at https://github.com/takuto-team/takuto-core; the CLI is at https://github.com/takuto-team/takuto-cli.

Do you collect any data or telemetry?

No. Takuto Core does not collect or transmit any telemetry — no usage analytics, no crash reporter, no phone-home. You can verify it yourself in the source.

All outbound traffic goes through an egress firewall that blocks everything by default and clears only what a run needs — your AI provider(s), GitHub/Jira, and package registries (add more with [network] extra_egress_hosts). Your ticket content, source code, and prompts go only to the AI provider you chose — Takuto Core itself never sees them — and with a self-hosted model, nothing leaves your infrastructure at all.

How is it isolated? Is it safe to run agents autonomously?

Isolation is a core design goal:

  • Each agent runs in its own container, so the blast radius of a prompt-injection attack is limited to that container.
  • The egress firewall limits what any agent can reach over the network. The default allowlist blocks everything except the hosts a run needs — the tightest setting, though enumerating every host gets fiddly with CDN-backed services like GitHub. Where that’s impractical, [network] allow_all_https permits all outbound HTTPS instead; paired with the per-container isolation above, that’s still a sound posture.
  • Branch protection is required — agents push branches and open PRs, never commit to main. Combined with scoped tokens (a fine-grained GitHub PAT, a limited Jira service account), this bounds what a hijacked session can actually do.

Takuto Core adds explicit untrusted-content framing around ticket text and optional byte caps, which reduces prompt-injection risk but does not eliminate it — human code review on PRs remains your backstop.

Which AI agents are supported?

  • Claude Code
  • Cursor Agent
  • Codex
  • OpenCode (for self-hosted models only)

You pick the provider in Configuration → AI Settings; each has its own [agent.providers.<name>] settings. See the configuration reference.

What hardware do I need?

These figures are rough estimates, not hard requirements — your real needs depend on the project, your provider, and your concurrency. For reference, the author develops and runs Takuto Core on an Apple M1 Pro with 16 GiB of RAM.

  • RAM: ≥ 8 GiB for a single workflow; ≥ 12 GiB on macOS with Podman (the VM needs its own share). Scale with [general] max_concurrent_workflows.
  • Disk: ≥ 30 GiB free — worktrees, npm/cargo caches, mise toolchains, and the optional Docker-in-Docker layer all live in Docker volumes.
  • OS: a Linux host is recommended for server deployments; macOS works well for local use.
  • Self-hosted models need considerably more — size GPU/VRAM to the model you intend to serve.

Why does my database connection fail when I use localhost?

Takuto runs inside a container, so a localhost connection string points back at Takuto itself, not at your database. Use the database container’s service name and its internal port on a shared Docker network (e.g. postgres://…@postgres:5432/…) — not localhost or the host-published port. With the CLI, pick “a database container running on this machine” in takuto setup and it wires this up for you. See External database.

Saving my GitHub PAT or AI key fails with a connection error — is my token wrong?

Usually not. Validating a token only reaches one provider endpoint, so a failure almost always points at a network/egress problem rather than a bad credential — often a CDN-backed host like api.github.com whose IPs rotate. Check that the egress allowlist resolves the provider’s current hosts, and add any missing ones with [network] extra_egress_hosts. See Configuration → network.

My self-hosted model returns “Model not found” or context errors.

Two common causes: (1) load the model in your server at the context width Takuto expects — set [agent.providers.opencode] context_limit to match what your server actually serves (LM Studio, for example, defaults to 4096, not 32768); and (2) the model id must match the provider’s exact API identifier. See Self-hosted models.

My saved API keys stopped working after I reset a Docker volume.

Credentials are encrypted with a master key (secret.key) stored on the takuto-data volume. If you delete or recreate that volume, keys sealed under the old master key can no longer be decrypted — the symptom is a confusing “authentication” or “not found” error rather than an obvious crypto failure. Re-open the provider settings and re-enter each key. To keep the master key stable across resets, provision TAKUTO_SECRET_KEY yourself instead of relying on auto-generation.

Agent CLI install fails or breaks at startup — what can I do?

Agent CLIs (claude / codex / opencode / cursor) are not baked into the image — Takuto installs them into the shared tools volume on first container start and refreshes to latest on every start. So a freshly published CLI release can break a previously working setup: install failures, a CLI that no longer launches, or behavior changes at runtime.

If you hit this, pin the CLI to a known-good version with version in that provider’s sub-table, so it stops tracking latest:

[agent.providers.claude]
version = "2.1.178"

This works for all four providers (claude, codex, opencode, cursor). Restart so the pinned version installs, then bump the pin deliberately once a newer release is verified. See Configuration → agent CLI installation & version pinning.

Who are commits and PRs attributed to — me or a bot?

Attribution follows your credentials, the same way for commits and pull requests: with a GitHub PAT, both are attributed to you; with a GitHub App alone (no PAT), both are attributed to the bot. There is no per-run toggle. See GitHub App.

Why doesn’t “Mark as Done” move my Jira ticket?

Mark as Done transitions the ticket to your [jira] done_status. It fails when your Jira project’s workflow has no transition from the ticket’s current status to that status, or when your token lacks transition permission. Set done_status to a status that is actually reachable in your board’s workflow. (The status name itself is matched language-independently, so localized names like “Terminé(e)” still resolve to “Done”.)

Can I host Takuto behind a public domain?

Yes. Put it behind a reverse proxy with TLS (see Install Takuto Core) and rely on the built-in multi-user authentication. Because that login is the gate and Takuto doesn’t yet support 2FA/OTP or security keys (passkeys/WebAuthn), use a strong, unique password for every account. Built-in protections help — argon2 password hashing, account lockout after repeated failed attempts, and per-IP rate limiting on login — but the password is your main line of defence for now. Keep branch protection and scoped tokens as the backstop.

Where do I go next?