安装 Takuto Core

这是自建 container 的路径：克隆 Takuto Core 引擎，编辑 config.toml，直接用 Docker Compose 运行它。当你想完全掌控镜像、部署以及前置网络时，就选这条路。

只想在一个项目上快速试试？Takuto CLI 会替你生成这些文件 并跑 Compose。两条路径跑的是同一个引擎。

前置条件

参见 概览 → 前置条件。简而言之：装好 docker compose 的 Docker（或 Podman）、≥ 8 GiB 内存、≥ 30 GiB 可用磁盘、一个 GitHub token，以及一个 AI 提供商账号。

单个开发者（本地）

在你的笔记本上运行 Takuto Core。请预留十五到二十分钟，因为这条路径会在本地构建 container 镜像。

1. 克隆并配置

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

编辑 config.toml：

  • 把 [general] ticketing_system 设为 "jira"、"github" 或 "none"。
  • 对 Jira：填写 [jira] site、project_keys 和 email。
  • 对 GitHub Issues：仓库会从克隆仓库的 git remote 自动识别。

把密钥放进 takuto.env（绝不要放进 config.toml）：

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

2. 构建

docker compose build

3. 认证（仅首次）

docker compose run --rm -it takuto setup

这会引导你依次完成 GitHub CLI → Atlassian CLI（可选）→ Claude Code 或 Cursor Agent → 克隆你的仓库。

macOS 上的 Podman： 先给 VM 增加资源：

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

4. 启动

docker compose up

仪表盘在 http://localhost:8080。首次启动时，创建初始的 admin 账号。如果你使用 Jira 或 GitHub Issues，轮询会自动开始；否则点击 + 手动启动一个 workflow。

团队部署（服务器）

把 Takuto Core 自托管在一台 Linux 服务器上。你的团队通过浏览器使用仪表盘；agent 在 后台运行。

1. 在服务器上克隆并配置

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

共享部署的关键设置：

[general]
ticketing_system = "jira"          # 或 "github"
max_concurrent_workflows = 3       # 调到与你服务器的 CPU/RAM 相称

[web]
host = "0.0.0.0"
port = 8080

Takuto Core 使用一个多用户数据库进行认证。首次启动时，仪表盘会提示你创建初始的 admin 账号；该 admin 随后可在 Configuration → Users 中创建更多用户。

2. 构建并认证

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

3. 作为服务启动

docker compose up -d

4. 前置一个反向代理（推荐）

Takuto Core 监听的是纯 HTTP。在它前面用指向 8080 端口的 nginx 或 Caddy 来终结 TLS。

Caddy 配置片段示例：

takuto.yourcompany.com {
    reverse_proxy localhost:8080
}

当处于 TLS 终结器之后时，设置仪表盘允许的来源，让 cookie 和 CORS 正常工作：

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

cookie_secure 会从 cors_origins 或入站的 X-Forwarded-Proto: https 头部自动识别 HTTPS；如果你的代理不发送该头部，就强制把它设为 true。完整的 [web] 表见 配置参考。

多用户模型

Takuto Core 是 多用户、单租户 的：每个用户都有自己的仪表盘视图，但同一实例上的 所有用户共享同一套 Jira、GitHub 和 AI 凭据。

  • admin —— 可以创建、编辑、停用和删除用户，并更改共享设置（轮询、并发、workspace 切换、仓库克隆）。
  • user —— 只能看到并操作自己创建的 workflow。不存在跨用户可见性，对 admin 也是 如此。

登录用的是用户名 + 密码（argon2 哈希）。会话有 24 小时的空闲 TTL 和 30 天的绝对 TTL； 账号在 10 分钟内 5 次失败尝试后会被锁定。账号创建时签发的一次性恢复码可用于重置忘记 的密码。

任何你给了账号的人，都能以该部署的身份在 worker container 里运行代码 —— 包括 takuto.env 里的 token。 不要把账号授予你不信任的人。

跨重启的持久性

所有认证状态（GitHub、Atlassian、Claude/Cursor）、workflow 快照以及 npm 缓存都存放在 命名的 Docker 卷里。workflow 能挺过 docker compose restart —— 暂停的或进行中的运行 会自动恢复。

可选的 sidecar

  • Docker-in-Docker —— 合并 docker-compose.dind.yml，让每个 workflow 的步骤跑在 临时的 Docker container 里（避免并发 workflow 之间的端口和文件系统冲突）。参见 扩展 Takuto Core。
  • 自托管模型桥接 —— 当你把 OpenCode 提供商指向运行在宿主 Mac 上的模型服务器时， 合并 docker-compose.lm-bridge.yml。参见 自托管模型。

后续步骤