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.
`auto_polling`	`true`	bool	UI: Item Polling	Cuando es `false`, el sondeo arranca en pausa. Usa Resume polling para recoger tickets.
`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.
`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 del usuario de Jira para la auth por token de `acli`.
`project_keys`	`[]`	array	UI: Item Polling	Claves de proyecto de Jira a sondear (p. ej. `["PROJ", "ENG"]`). El selector + se oculta cuando está vacío.
`item_types`	`["Task", "Bug"]`	array	UI: Item Polling	Tipos de ticket que recoge el poller. El selector manual + muestra todas las issues que no sean Epic.
`done_status`	`"Done"`	string	UI: Item Polling	Transición disparada por Mark as Done. Debe coincidir con una transición real de tu workflow de Jira.
`jql_filter`	`""`	string	UI: Item Polling	JQL extra fusionado con `AND` en el selector +. Las Epics siempre se excluyen.
`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).

`[polling]`

Política de sondeo de ítems ajustable por el admin: qué ítems descubiertos auto-añaden los pollers, qué flow auto-inician y cuántos corren en paralelo. Se leen en vivo en cada ciclo (sin reinicio). Todas las claves de [polling] se gestionan desde la UI en Configuración → Item Polling.

Clave	Por defecto	Tipo	Scope	Descripción
`auto_start_flow`	`""`	string	UI: Item Polling	Slug del único flow a auto-iniciar por ítem sondeado. Vacío = iniciar todos los flows sin dependencias.
`max_parallel_items`	`0`	int	UI: Item Polling	Tope de ítems ocupando una ranura de concurrencia a la vez. `0` = sin límite.
`max_parallel_per_user`	`false`	bool	UI: Item Polling	Cuando es `true`, `max_parallel_items` se cuenta por propietario del workflow; `false` lo cuenta globalmente.

`[polling.jira]`

Clave	Por defecto	Tipo	Scope	Descripción
`summary_keywords`	`[]`	array	UI: Item Polling	Coincidencia de subcadena ANY insensible a mayúsculas contra el resumen del ticket. Vacío = sin filtro.

`[polling.github]`

Clave	Por defecto	Tipo	Scope	Descripción
`labels`	`[]`	array	UI: Item Polling	Pertenencia exacta de label, coincidencia ANY. Vacío = sin filtro.
`title_keywords`	`[]`	array	UI: Item Polling	Coincidencia de subcadena ANY insensible a mayúsculas contra el título de la issue. Vacío = sin filtro.

`[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://maestro.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`.
`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? 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 (p. ej. localhost:5433), y pon ambos containers en la misma red. 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>]`.
`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.

`[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.
`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 `maestro` 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 `$MAESTRO_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 `MAESTRO_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.

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/maestro/env). Solo se honran las líneas export VAR=value.

Variable	Propósito
`ANTHROPIC_API_KEY` 🔒	API key de Claude (o usa OAuth vía `claude login`).
`ANTHROPIC_BASE_URL`	Anula el endpoint de la API de Anthropic (proxy / gateway on-prem).
`CLAUDE_CODE_OAUTH_TOKEN` 🔒	Token para la auth OAuth de Claude Code.
`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).
`MAESTRO_CONFIG`	Ruta a un `config.toml` alternativo.
`MAESTRO_DATA_DIR`	Anula el directorio de datos persistente (`maestro.db`, snapshots).
`MAESTRO_HOME`	Anula la base home usada para calcular `MAESTRO_DATA_DIR`.
`MAESTRO_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"