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.

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 (o un login de Claude Pro/Max) para Claude Code, 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) — un token de API de Atlassian para la cuenta como la que Takuto deba actuar.

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

2. Instala la CLI

Homebrew (macOS / Linux — recomendado):

brew install takuto-team/tap/takuto

Para descargas manuales del binario (incluido Windows), 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.

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. Autentícate y añade un proyecto

Añade los tokens del paso 1, y luego apunta Takuto a un repositorio:

  • Recomendado — los tokens del paso 1: introduce tu key de proveedor y tu token de GitHub (ANTHROPIC_API_KEY, CURSOR_API_KEY, OPENAI_API_KEY, un GH_TOKEN acotado…) desde las pantallas de Configuración del dashboard, o ponlos en .takuto/takuto.env antes de arrancar (consulta Configuración).
  • Haz clic en “Setup a New Project” en el dashboard para clonar el repositorio en el que quieres que trabaje Takuto.
  • Si configuraste Jira o GitHub Issues, el sondeo empieza automáticamente y recoge los tickets en “To Do”. Si no, 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.