Inicio rápido

La vía canónica de “pruébalo ya”: instala la Takuto CLI, ejecuta takuto setup y luego takuto start, y termina en el dashboard. Lleva unos minutos.

Estado de las pruebas por proveedor (beta). Claude Code se verificó por última vez antes de que Anthropic hiciera obligatoria una API key para su modo headless, y Codex aún no se ha probado. Deberían funcionar igualmente, pero puede que te topes con algún detalle áspero. Si es así, cuéntanoslo — el feedback es muy bienvenido y nos ayuda a resolver cualquier problema rápidamente.

Configuración recomendada. Unas pocas decisiones hacen que la ejecución sea más fluida y esté más lista para producción:

• Autentica GitHub con una GitHub App, no con un personal access token (PAT). Así los PRs se abren bajo una identidad de bot dedicada en lugar de tu cuenta personal — autoría más limpia, y el acceso queda acotado a lo que concede la app.
• Protege las ramas a las que apunta el agente. Un agente autónomo puede hacer cualquier cosa que su token le permita, así que activa la branch protection en main (y en cualquier rama destino): exige un PR antes de mergear, exige una revisión aprobatoria y prohíbe los pushes directos. Combinado con una identidad de bot, esto te da una barrera de revisión obligatoria incluso cuando trabajas en solitario.
• Usa una base de datos externa (Postgres / MySQL / MariaDB) para que tus datos vivan fuera del container y se puedan respaldar.

Todo lo de abajo funciona sin esto, pero merece la pena configurarlo pronto.

¿Prefieres ejecutar el motor por tu cuenta sin la CLI? Consulta Instalar Takuto Core para la vía de crea-tu-propio-container.

1. Crea los tokens que vas a necesitar

Ten esto a mano antes de empezar — los añadirás en el dashboard (paso 6):

• Una credencial de proveedor de IA — una de: una API key de Anthropic para Claude Code (su modo headless ahora exige una API key), una API key de OpenAI para Codex, una API key de Cursor para Cursor Agent — o ninguna si ejecutas un modelo autoalojado a través de OpenCode.
• Acceso a GitHub — un personal access token de grano fino acotado a los repos en los que Takuto vaya a trabajar (Contents y Pull requests: read & write; Metadata: read; Issues: read & write si haces polling de GitHub Issues). Mejor aún, configura una GitHub App para que los PRs vengan de una identidad de bot acotada en lugar de tu cuenta personal.
• Jira (solo si vas a hacer polling de Jira) — tu propio token de API de Atlassian. Cada usuario añade su propio token en el dashboard (Configuration → Ticketing); las lecturas y escrituras actúan entonces como tú. Un token de propietario para todo el despliegue es solo una reserva para los usuarios que no hayan añadido uno.

Acota cada token al mínimo que necesite — estos delimitan lo que un agente autónomo puede alcanzar.

2. Instala la CLI

brew install takuto-team/tap/takuto

# Apple Silicon (arm64) — para Intel es 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/

brew install takuto-team/tap/takuto

# amd64 — para arm64 es 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/

# Descarga el binario más reciente para Windows
curl.exe -L -o takuto.exe https://github.com/takuto-team/takuto-cli/releases/latest/download/takuto-windows-amd64.exe
# Luego mueve takuto.exe a una carpeta que esté en tu PATH (p. ej. un directorio de herramientas)

brew install takuto-team/tap/takuto

# amd64 — para arm64 es 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/

Para todos los binarios y sumas de verificación, consulta la página de Releases y la referencia de la CLI.

3. Requisitos previos

Lo único que necesitas instalado es Docker o Podman — la CLI detecta automáticamente cuál tienes.

• Docker Desktop
• Podman

No descargas la imagen de Takuto Core tú mismo: takuto start la descarga en la primera ejecución (y recurre a una copia en caché si estás sin conexión). Se publica de forma pública, así que no hace falta autenticarse en ningún registro — aunque puedes descargarla por adelantado a mano con docker pull ghcr.io/takuto-team/takuto-core:latest si lo prefieres.

4. Genera tu configuración

takuto setup

El asistente es corto: ahora que el dashboard gestiona la mayor parte de la configuración, solo te pregunta por el puerto del dashboard y — si usas una base de datos externa (Postgres / MySQL / MariaDB) — sus datos de conexión (si no, usa por defecto el SQLite integrado). Todo lo demás — sistema de ticketing, proveedor de IA y modelos, sondeo, workflows — se configura después en el dashboard. Genera takuto.yml más una carpeta .takuto/ con config.toml, los secretos (takuto.env) y una carpeta workflows/ con definiciones de pipeline de inicio:

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

La carpeta .takuto/ se crea allí donde ejecutes el comando — no tiene por qué ser un directorio de proyecto. Ejecuta takuto setup/takuto start desde distintas carpetas para mantener varias instancias aisladas de Takuto una al lado de otra: cada una con su propia configuración, autenticación, workspaces y base de datos, sin configuración extra alguna.

¿Apuntas a una base de datos externa — sobre todo una que corre en un container? Acertar con la cadena de conexión es la única parte delicada: consulta Base de datos externa.

5. Arranca Takuto

takuto start

Luego abre el dashboard en tu navegador — por defecto http://localhost:8080, o el puerto que elegiste durante takuto setup. takuto start descarga la imagen (en la primera ejecución) y levanta el stack. En el primer arranque, el dashboard te pide crear la cuenta admin inicial.

6. Termina en el dashboard

En el primer arranque, el dashboard te guía por un breve asistente de configuración, en orden:

1. GitHub — tu PAT, o una GitHub App para commits y PRs atribuidos a un bot.
2. Repositories — clona el repo (o los repos) en los que quieres que trabaje Takuto.
3. AI provider — la key de tu proveedor (ANTHROPIC_API_KEY, CURSOR_API_KEY, OPENAI_API_KEY…), o un endpoint autoalojado.
4. Ticketing — Jira o GitHub Issues, más el sondeo por repositorio (project keys, item types, filtros) fijado para cada repo. Cada usuario añade aquí su propio token de Jira.
5. Workflows — revisa las pipelines TOML sembradas.

Los valores existentes rellenan sus campos por adelantado (los secretos muestran un marcador ••••••); también puedes poner los secretos en .takuto/takuto.env antes de arrancar (consulta Configuración). Una vez configurados un repositorio y el ticketing, el sondeo empieza automáticamente y recoge los tickets en “To Do” — o haz clic en + para pegar una descripción y lanzar un workflow manualmente.

Opcional — takuto auth (no recomendado). takuto auth ejecuta logins OAuth interactivos (GitHub + tu proveedor de IA) desde la CLI. OAuth concede acceso amplio a la cuenta, así que recomendamos en su lugar API keys/tokens acotados (arriba). Usa takuto auth solo si necesitas específicamente el flujo de login interactivo.

Qué pasa a continuación

Cada workflow crea un git worktree a partir de tu rama base, ejecuta tus comandos de worktree-init (p. ej. npm ci) y luego ejecuta los pasos del agente desde tu definición de workflow en TOML. Observa la salida de terminal en vivo en cada tarjeta de workflow, y abre un editor VS Code en el navegador sobre cualquier worktree con Open editor.

Consulta Cómo funciona para el ciclo de vida completo de un workflow, y la referencia de la CLI para stop, restart y el aislamiento multiproyecto.

Parar y reiniciar

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

Todo el estado de autenticación, los snapshots de workflow y las cachés viven en volúmenes de Docker con nombre, así que los workflows sobreviven a un reinicio — las ejecuciones en pausa o en curso se reanudan automáticamente.