Referencia de configuración

Esta es la referencia clave por clave de config.toml. El config.toml.example anotado en la raíz del repositorio de Takuto Core es la fuente de verdad — cuando esta página y ese archivo no coincidan, gana el ejemplo.

Los ajustes se recargan al cambiar el archivo (un poller de 5 segundos). Unas pocas claves son solo de arranque y necesitan un reinicio (se indica en línea). Los secretos van en takuto.env, nunca en config.toml — consulta Variables de entorno.

Takuto Core divide la configuración en dos tipos:

Bootstrap — necesarios antes de que existan la base de datos/el dashboard, o aplicados solo en el arranque. Edítalos a mano en config.toml antes del primer arranque.
Gestionados por la UI — tienen un valor por defecto sensato y normalmente se editan desde una pantalla de Configuración del dashboard. La UI escribe los cambios de vuelta a config.toml, así que el archivo sigue siendo el almacén; un valor fijado aquí es solo un valor por defecto del momento del despliegue.

La columna Scope marca cada clave como Bootstrap o nombra la superficie del dashboard que la gestiona. 🔒 marca las claves sensibles para la seguridad — revísalas antes de cambiarlas en un despliegue compartido.

`[general]`

Comportamiento global del proceso: modo de ticketing, sondeo, concurrencia, logging.

Clave	Por defecto	Tipo	Scope	Descripción
`ticketing_system`	`"none"`	string	Bootstrap	`"jira"`, `"github"` o `"none"`. Gobierna el poller y el botón + del dashboard.
`dry_mode` 🔒	`false`	bool	Bootstrap	Omite los efectos secundarios reales de Jira/GitHub (sin asignaciones, transiciones ni pushes). El trabajo local — worktrees, installs, sesiones de agente — sigue ejecutándose. Útil para preparar una definición de workflow antes de salir en vivo.
`log_level`	`"info"`	string	Bootstrap (restart)	`trace`, `debug`, `info`, `warn`, `error`.
`worker_image`	`""`	string	Bootstrap	Imagen de Docker para los containers de workflow aislados cuando DinD está activo. Vacío = detección automática a partir de la imagen de Takuto en ejecución.
`workflow_definitions_dir`	`"workflows"`	string	Bootstrap (restart)	Ruta escaneada en busca de los workflows `.toml` que siembran* los valores por defecto de un nuevo usuario/workspace. Los workflows en vivo se editan en el dashboard (Configuration → Workflows); editar el TOML más tarde no cambia los workspaces ya sembrados.
`allow_auto_generate_secret_key` 🔒	`true`	bool	Bootstrap	Cuando es `true`, el servidor autogenera `{data_dir}/secret.key` en el primer arranque si no hay ninguna clave presente. Fíjalo en `false` para aprovisionar la clave por fuera.
`poller_owner_username`	(sin definir)	string	Bootstrap	Usuario propietario de los workflows creados automáticamente por el poller. Cuando no se define, se usa el primer admin no suspendido por orden lexicográfico.
`migrate_orphan_workflows`	`false`	bool	Bootstrap	Cuando es `true`, los workflows restaurados sin propietario (huérfanos previos al multiusuario) se reasignan al propietario del poller resuelto en el arranque.
`migrate_orphan_repo_associations`	`true`	bool	Bootstrap	Cuando es `true`, la reconciliación del arranque enlaza los workflows restaurados con su repositorio registrado correspondiente.
`poll_interval_secs`	`60`	int	UI: Item Polling	Segundos entre sondeos de Jira/GitHub.
`pr_merge_poll_interval_secs`	`60`	int	UI: Item Polling	Segundos entre sondeos que comprueban si el PR de un workflow se ha mergeado en GitHub. `0` lo desactiva.
`max_concurrent_workflows`	`1`	int	UI: Item Polling	Tamaño del semáforo para las sesiones paralelas de mise/install/agente. Ajústalo a tu CPU y RAM.
`max_active_workflows`	`0`	int	UI: Item Polling	Máximo de workflows visibles en el dashboard (todas las filas). El poller no inicia tickets nuevos en este límite. `0` replica `max_concurrent_workflows`.
`max_concurrent_manual_workflows`	`0`	int	UI: Item Polling	Tope de arranques manuales con + que no estén en Done/Stopped/Error. `0` = sin límite.
`max_parallel_per_user`	`false`	bool	UI: Item Polling	Cuando es `true`, el tope de ítems en paralelo por repositorio se cuenta por propietario del workflow; `false` lo cuenta globalmente.
`generate_report`	`false`	bool	UI: Item Polling	Cuando es `true`, cada paso del agente añade hallazgos a un informe y un paso final los consolida. Suma tokens.
`work_item_log_retention_days`	`7`	int	UI: Item Polling	Días de líneas de log de work-item que retener antes de la limpieza. `0` = conservar para siempre.

`[jira]`

Solo se usa cuando [general] ticketing_system = "jira".

Clave	Por defecto	Tipo	Scope	Descripción
`site`	`""`	string	Bootstrap	Host de Jira o URL `https://` completa (p. ej. `"yourcompany.atlassian.net"`). Gobierna la auth por token, la allowlist de egress y el enlace de Jira en el cuerpo del PR.
`email`	`""`	string	Bootstrap	Correo de cuenta de Jira de reserva — usado para el token del propietario/`acli` solo cuando un usuario no ha añadido su propio token de Jira. En caso contrario, las lecturas y escrituras pasan por el propio token REST de Jira de cada usuario.
`done_status`	`"Done"`	string	UI: Item Polling	Estado al que Mark as Done transiciona el ticket. Se compara de forma independiente del idioma (por `statusCategory`), así que un nombre localizado como “Terminé(e)” sigue resolviéndose a “Done”; si falla, el error lista los estados disponibles.
`linked_items_in_prompt`	`"full"`	string	UI: Item Polling	`"full"` \| `"summary_only"` \| `"omit"` — cómo aparece el texto de las issues enlazadas en `{ticket_context}`.
`ticket_context_max_description_bytes`	`0`	int	UI: Item Polling	Tope para la descripción del ticket principal en `{ticket_context}`. `0` = sin límite (el valor por defecto).
`linked_issue_description_max_bytes`	`0`	int	UI: Item Polling	Tope por descripción de issue enlazada cuando `linked_items_in_prompt = "full"`. `0` = sin límite (el valor por defecto).

Ahora por usuario y por repositorio: el token de Jira de cada usuario (añadido en Configuration → Ticketing), más las project keys, los item types y el filtro JQL — todo ha salido de config.toml. El token del propietario del despliegue / acli es solo una reserva para los usuarios que no hayan añadido el suyo.

`[git]`

Todas las claves de [git] son ajustes Bootstrap.

Clave	Por defecto	Tipo	Scope	Descripción
`base_branch`	`"main"`	string	Bootstrap	Rama desde la que se crea cada worktree.
`remote`	`"origin"`	string	Bootstrap	Remote de Git usado para fetch, ref base y push.
`repo_path`	`"/workspace"`	string	Bootstrap	Ruta al repo clonado dentro del container. El nombre del workspace se deriva del último componente de esta ruta.

`[github]`

Autenticación opcional con GitHub App. Cuando se configura, los commits y los PRs se atribuyen a la cuenta bot en lugar de a tu usuario gh personal. Los tres campos (app_id, app_installation_id y una fuente de clave privada) deben fijarse juntos; los errores no son fatales — Takuto Core recurre a la auth gh personal y registra un warning. Permisos de App requeridos: contents (write), pull_requests (write), metadata (read).

Clave	Por defecto	Tipo	Scope	Descripción
`app_id`	(sin definir)	int	Bootstrap	ID de la GitHub App.
`app_installation_id`	(sin definir)	int	Bootstrap	ID de instalación de la App para tu org/repo.
`app_private_key` 🔒	(sin definir)	string	Bootstrap	Clave privada RSA codificada en PEM, en línea. Mutuamente excluyente con `app_private_key_path`. Es preferible mantenerla en `takuto.env`.
`app_private_key_path` 🔒	(sin definir)	string	Bootstrap	Ruta a un archivo PEM con la clave privada de la App.

`[web]`

El servidor del dashboard.

Clave	Por defecto	Tipo	Scope	Descripción
`host`	`"0.0.0.0"`	string	Bootstrap (restart)	Dirección de bind.
`port`	`8080`	int	Bootstrap (restart)	Puerto de bind.
`cors_origins` 🔒	`[]`	array	Bootstrap (restart)	Orígenes CORS permitidos. Vacío = autocalcular a partir de `host`/`port`. Fíjalos explícitamente detrás de un reverse proxy o un terminador de TLS (p. ej. `["https://takuto.example.com"]`).
`cookie_secure` 🔒	(detección automática)	bool	Bootstrap	Controla el flag `Secure` en la cookie de sesión. Se detecta automáticamente a partir de `cors_origins` `https://` o una cabecera entrante `X-Forwarded-Proto: https`. Fíjalo en `true` al terminar TLS sin esa cabecera; `false` solo para pruebas locales en HTTP plano.
`kick_other_sessions_on_login`	`true`	bool	Bootstrap	Cuando es `true`, un login exitoso borra las sesiones previas del mismo usuario. Fíjalo en `false` para sesiones concurrentes de escritorio + móvil.

La autenticación es solo multiusuario. En el primer arranque el dashboard te pide crear la cuenta admin inicial. Las claves heredadas de usuario único [web] dashboard_username / dashboard_password se han eliminado — si están presentes en un config.toml antiguo, se ignoran en silencio.

Políticas de sesión (no configurables): TTL de inactividad 24 h; TTL absoluto 30 días; bloqueo de cuenta tras 5 intentos fallidos de login/recuperación en 10 min (el admin lo limpia con POST /api/users/{id}/unlock); rate limit por IP en /api/auth/login y /api/auth/recover de 10 / minuto.

`[database]`

Donde Takuto guarda usuarios, sesiones y snapshots. Omite la sección (o deja connection vacía) para mantener el valor por defecto de SQLite sin configuración en {data_dir}/takuto.db. Fija connection para usar una PostgreSQL / MariaDB / MySQL externa. Solo se aplica en el reinicio — PUT /api/config no parchea esta sección; los cambios de backend necesitan un reinicio del proceso.

Clave	Por defecto	Tipo	Scope	Descripción
`connection` 🔒	`""`	string	Bootstrap (restart)	URL de la base de datos. Vacía → SQLite. Esquemas: `sqlite://…`, `postgres://…` / `postgresql://…`, `mysql://…` (también cubre MariaDB). La contraseña se redacta en `GET /api/config`.
`local_container`	(sin definir)	bool	Bootstrap (CLI)	Solo CLI. Marca `connection` como una URL orientada al host (p. ej. `localhost:5433`) para un container de base de datos en esta máquina. En `takuto start`, el CLI encuentra ese container, lo conecta a la red de Takuto como `takuto_db` y reescribe la conexión. El motor ignora esta clave. Consulta Base de datos externa.
`max_connections`	`10`	int	Bootstrap (restart)	Tamaño del pool de conexiones.
`acquire_timeout_secs`	`30`	int	Bootstrap (restart)	Cuánto esperar por una conexión del pool antes de agotar el tiempo.
`idle_timeout_secs`	`600`	int	Bootstrap (restart)	Tiempo de vida de una conexión inactiva.
`fail_fast` 🔒	`true`	bool	Bootstrap (restart)	Cuando es `true`, se ejecuta una sonda `SELECT 1` de 5 s al arrancar y aborta si el backend es inalcanzable. Cuando es `false`, registra un warning y recurre a SQLite local para ese proceso.
`import_from_sqlite`	`true`	bool	Bootstrap (restart)	En la primera conexión a un backend externo nuevo, copia una sola vez los datos del SQLite local existente (las sesiones expiran, así que los usuarios vuelven a autenticarse). Se omite en reinicios posteriores.

¿Ejecutas la base de datos en un container? Con el CLI, pon local_container = true y da la URL de localhost que usarías desde tu host — takuto start la cablea en la red de Takuto por ti. Ejecutando el motor directamente, el host de connection debe ser alcanzable desde dentro del container de Takuto — usa el nombre del container de la base de datos y su puerto interno (p. ej. takuto_db:5432), no localhost ni el puerto publicado en el host. El recorrido completo está en Base de datos externa.

`[agent]`

El proveedor de IA para los pasos de workflow que llevan prompt. Cada clave de [agent] se gestiona desde la UI en Configuración → AI Settings; los valores de aquí son los valores por defecto del momento del despliegue.

Clave	Por defecto	Tipo	Scope	Descripción
`provider`	`"claude"`	string	UI: AI Settings	`"claude"`, `"cursor"`, `"codex"` u `"opencode"`. Cada uno lee su propia sub-tabla `[agent.providers.<name>]`.
`available_providers`	los cuatro	array	UI: AI Settings	Proveedores contra los que los usuarios pueden autenticarse y entre los que pueden cambiar. También determina qué CLIs de agente se instalan en el arranque y qué hosts de proveedor habilita el egress firewall — recórtalo para estrechar ambas cosas.
`step_timeout_secs`	`1800`	int	UI: AI Settings	Timeout por paso en segundos. Se aplica a todos los proveedores.
`improve_timeout_secs`	`300`	int	UI: AI Settings	Timeout en segundos para la acción de refinamiento de descripción por IA («improve»).
`share_conversation_across_steps`	`false`	bool	UI: AI Settings	Compartir una conversación del agente entre los pasos de un flow frente a una sesión nueva por paso.
`max_repeated_output_lines`	`8`	int	UI: AI Settings	Guardarraíl de no-progreso. Aborta un paso cuando su salida repite la misma línea sustantiva esta cantidad de veces seguidas. `0` lo desactiva.

Los ajustes por proveedor (modelo, endpoint, ruta de la CLI, args extra) viven en las sub-tablas [agent.providers.<name>]. Campos comunes: model, extra_args, allow_shared_default; Claude/Codex/OpenCode usan base_url, Cursor usa cli.

Instalación de las CLIs de agente y fijación de versión

Las CLIs de agente se instalan en el primer arranque, no vienen horneadas en la imagen. Takuto instala la CLI (claude / codex / opencode / cursor) en el volumen de herramientas compartido la primera vez que arranca un container, para cada proveedor de available_providers.

Por defecto, cada CLI se instala (y se refresca) a la latest en cada arranque. Para fijar una versión concreta, define version en la sub-tabla de ese proveedor:

[agent.providers.claude]
version = "2.1.178"   # omítelo o déjalo vacío para seguir la latest

[agent.providers.codex]
version = "0.9.4"

Valor de `version`	Comportamiento
`"2.1.178"` (una versión concreta)	Instala esa versión exacta; nunca se auto-actualiza.
`""` u omitido	Instala/refresca la latest en cada arranque del container.

La fijación funciona para los cuatro proveedores de agente (claude, codex, opencode, cursor).

La CLI de Atlassian (acli) también se instala, pero Atlassian solo sirve latest, así que su fijación [jira] acli_version es orientativa — siempre se instala la latest.

`[agent.providers.cursor]`

Se usa solo cuando provider = "cursor".

Clave	Por defecto	Tipo	Scope	Descripción
`cli`	`"agent"`	string	UI: AI Settings	Nombre del ejecutable de Cursor Agent o ruta absoluta.
`model`	`"Auto"`	string	UI: AI Settings	`--model` de Cursor Agent. `"Auto"` o vacío = selección automática.
`privacy_mode`	`true`	bool	UI: AI Settings	El modo privacy de Cursor. Si lo dejas activado (`true`), Cursor no conserva tu código ni lo usa para entrenar sus modelos. Ponlo en `false` solo si tu plan y tu política de Cursor lo permiten — al hacerlo se relajan esas garantías y tu código se envía a Cursor bajo sus términos de datos estándar.
`extra_args`	`[]`	array	UI: AI Settings	Flags de CLI extra (con deny-list aplicada).

`[agent.providers.opencode]`

El adaptador de OpenCode (autoalojado, compatible con OpenAI). Se usa solo cuando provider = "opencode". Consulta Modelos autoalojados.

Clave	Por defecto	Tipo	Scope	Descripción
`model`	`""`	string	UI: AI Settings	Id del modelo servido por el endpoint (el `<model>` en `-m self_hosted/<model>`). Obligatorio cuando está activo.
`base_url`	`""`	string	UI: AI Settings	URL del endpoint compatible con OpenAI (p. ej. `http://lm-studio:1234/v1`). Obligatorio cuando está activo.
`extra_args`	`[]`	array	UI: AI Settings	Flags de CLI extra (con deny-list aplicada).
`allow_shared_default`	`false`	bool	UI: AI Settings	Permite que los usuarios sin un bearer personal recurran al token por defecto del despliegue.
`context_limit`	`32768`	int	UI: AI Settings	Ventana de contexto máxima (tokens) del modelo autoalojado. Hazla coincidir con la longitud de contexto cargada en tu servidor.
`output_limit`	`8192`	int	UI: AI Settings	Tokens de salida máximos por respuesta.

Claude y Codex usan sus propias sub-tablas [agent.providers.claude] / [agent.providers.codex] con model, base_url y extra_args, todas editables desde Configuración → AI Settings.

`[docker]`

Todas las claves de [docker] son Bootstrap (consumidas en el build de la imagen / el compose up).

Clave	Por defecto	Tipo	Scope	Descripción
`build_commands`	`[]`	array	Bootstrap	Pasos `bash -c` opcionales ejecutados durante el build de la imagen.
`compose_up_commands`	`[]`	array	Bootstrap	Comandos opcionales ejecutados como el usuario `takuto` tras el preflight en cada `docker compose up`.

`[editor]`

El VS Code en el navegador (openvscode-server) y el reenvío dinámico de puertos. Todas las claves de [editor] son Bootstrap.

Clave	Por defecto	Tipo	Scope	Descripción
`ports`	`[]`	array	Bootstrap	Puertos de aplicación a exponer al abrir el editor (p. ej. `[3000, 5173, 6006]`). Cada uno se mapea a un puerto del host del rango 9100–9200 y se muestra en la tarjeta del workflow.
`dynamic_ports`	`10`	int	Bootstrap	Puertos de reserva preasignados para el reenvío automático del dev-server. `0` lo desactiva.
`theme`	`""`	string	Bootstrap	Tema de color de VS Code; vacío usa el tema por defecto del propio editor (p. ej. `"One Dark Pro"`).
`extensions`	`[]`	array	Bootstrap	IDs del marketplace a preinstalar (p. ej. `["esbenp.prettier-vscode"]`).
`settings`	`{}`	table	Bootstrap	Ajustes libres de VS Code bajo `[editor.settings]`.

`[terminal]`

La terminal web (ttyd) dentro del container del editor. Todas las claves de [terminal] son Bootstrap.

Clave	Por defecto	Tipo	Scope	Descripción
`git_editor`	(sin definir)	string	Bootstrap	Paquete apt (p. ej. `"nano"`, `"vim"`) instalado en cada container del editor; `git config core.editor` se fija a él.
`setup_commands`	`[]`	array	Bootstrap	Comandos de shell ejecutados una vez por vida del container del editor (protegidos por un archivo marcador).
`startup_commands`	`[]`	array	Bootstrap	Comandos de shell ejecutados cada vez que se crea un container del editor nuevo.

`[network]`

Política de firewall — solo del momento del despliegue. Todas las claves de [network] son Bootstrap.

La allowlist es consciente del proveedor: el firewall habilita automáticamente los hosts de la API del proveedor (o los proveedores) de IA que actives — el [agent].provider activo más todos los proveedores de [agent].available_providers (Claude, Codex/OpenAI, Cursor) y cualquier base_url autoalojado. Con la config por defecto (los cuatro proveedores disponibles) todos los proveedores soportados son alcanzables de fábrica; recorta available_providers para estrechar el firewall a solo los proveedores que uses. Los hosts exactos se resuelven en el momento de aplicar la política mediante el comando takuto egress-hosts del core.

Clave	Por defecto	Tipo	Scope	Descripción
`extra_egress_hosts` 🔒	`[]`	array	Bootstrap	Dominios añadidos a la allowlist de egress sobre los valores por defecto integrados (tus proveedores de IA, Atlassian, GitHub, registro de npm, registros detectados en `.npmrc`). Cada entrada amplía la superficie de ataque — añade solo hosts que confíes en que el agente alcance.
`allow_all_https` 🔒	`false`	bool	Bootstrap	Cuando es `true`, omite la allowlist y permite todo el HTTPS saliente (443/8443). `extra_egress_hosts` se ignora. Úsalo solo en entornos de confianza — esto desactiva una de las mitigaciones centrales de Takuto Core.

`[provisioning]`

Herramientas de CLI extra instaladas en el volumen de herramientas compartido en el arranque, sobre las que vienen horneadas en la imagen. Úsalo para fijar la versión de una herramienta, añadir una que se quitó del horneado, o saltarte una por completo. Bootstrap (aplicado en el arranque). Consulta Extender Takuto Core.

Clave	Por defecto	Tipo	Scope	Descripción
`install_commands`	`[]`	array	Bootstrap	Snippets de shell ejecutados en orden contra el volumen de herramientas. Protegidos por SHA: se reejecutan solo cuando cambia la lista. Cada snippet debe ser idempotente e instalar en `$TAKUTO_TOOLS_BIN`.

`[dev]`

Perillas solo para desarrollo. Déjalas comentadas en producción. Todas las claves de [dev] son Bootstrap.

Clave	Por defecto	Tipo	Scope	Descripción
`mock_agent`	`false`	bool	Bootstrap	Cuando es `true`, las sesiones del agente cortocircuitan a un mock con guion — sin proceso real de `claude`/`agent`, sin tokens consumidos. Respeta `TAKUTO_DEV_MOCK_AGENT=1`.
`mock_agent_script_path`	(sin definir)	string	Bootstrap	Ruta al archivo del guion del mock. Sin valor por defecto — `tmp/mock_script.txt` es solo el ejemplo sugerido.
`mock_agent_line_delay_ms`	`75`	int	Bootstrap	Retardo entre líneas de salida del mock.
`mock_agent_total_ms`	`5000`	int	Bootstrap	Duración total de la sesión mock.

Secciones ignoradas

Las siguientes secciones se ignoran por completo al cargar — se registra un warning de arranque para que te enteres, pero su contenido nunca se lee. Salieron de config.toml porque son por usuario y por workspace, y ahora viven solo en la base de datos, editadas desde el dashboard:

[commands] — los comandos de inicialización del worktree (antes pre_install, install, pre_workflow, ahora worktree_init_commands) viven en la base de datos, se resuelven por (user, workspace) y se editan desde Configuración → Worktree Settings.
[[run_commands]] — los comandos de dev-server de larga duración expuestos como botones de run/stop son por usuario y se configuran desde la misma pestaña de Worktree Settings.
[polling] (y [polling.jira] / [polling.github]) — los filtros de sondeo, el flow de auto-inicio y el tope de ítems en paralelo por repo son por usuario y por repositorio, fijados en Configuration → Ticketing. Los límites de todo el despliegue siguen en [general].
[jira] project_keys / item_types / jql_filter — también por usuario y por repositorio (la misma pestaña de Ticketing).
[general] auto_polling — el sondeo ahora se activa por repositorio; el control de Pause/Resume del dashboard es el interruptor maestro global.

Para [commands] / [[run_commands]] no hay fallback de configuración: si una sección está ausente de la base de datos, el workflow simplemente no ejecuta ningún comando para ella.

Variables de entorno

Los secretos y las anulaciones por host van en takuto.env (montado en /etc/takuto/env). Solo se honran las líneas export VAR=value.

Variable	Propósito
`ANTHROPIC_API_KEY` 🔒	API key de Claude — obligatoria para el pipeline headless (Anthropic ya no acepta OAuth de Pro/Max en modo desatendido).
`ANTHROPIC_BASE_URL`	Anula el endpoint de la API de Anthropic (proxy / gateway on-prem).
`CLAUDE_CODE_OAUTH_TOKEN` 🔒	Token de un `claude login` interactivo. No sirve para el pipeline headless desatendido — usa `ANTHROPIC_API_KEY` ahí.
`CURSOR_API_KEY` 🔒	Key de Cursor Agent — se salta el preflight interactivo de `agent status`.
`GH_TOKEN` 🔒	PAT de GitHub (de grano fino, acotado al repo de destino).
`TAKUTO_CONFIG`	Ruta a un `config.toml` alternativo.
`TAKUTO_DATA_DIR`	Anula el directorio de datos persistente (`takuto.db`, snapshots).
`TAKUTO_HOME`	Anula la base home usada para calcular `TAKUTO_DATA_DIR`.
`TAKUTO_DEV_MOCK_AGENT`	`1` = fuerza la activación del agente mock (anula `[dev] mock_agent`).

Ejemplo de takuto.env:

export ANTHROPIC_API_KEY="sk-ant-..."
export GH_TOKEN="github_pat_..."
export ANTHROPIC_BASE_URL="https://custom-proxy.example.com/claude"