Saltar a contenido

Configuración del workspace

Cada workspace tiene un fichero de configuración pequeño que tu equipo mantiene con el repositorio: .chronos/settings.toml. Se commitea, se revisa en pull request y nunca contiene secretos. Chronos lo crea con valores razonables la primera vez que abres un workspace.

.chronos/settings.toml

[workspace]
base_branch = "main"      # la rama de la que parten las sesiones y contra la que se comparan
remote = "origin"         # el remoto que se usa al abrir pull requests

# Scripts con nombre que define tu equipo (se revisan como cualquier otro código).
# Se lanzan por nombre desde la app, nunca como texto libre.
[scripts]
setup   = "pnpm install"          # corre al crear la sesión
run     = "pnpm dev"              # comando de desarrollo de larga duración (lee CHRONOS_PORT)
run_mode = "server"               # cómo se comporta `run` (`server`, `oneshot`)
archive = "pnpm clean"            # corre al cerrar la sesión
test    = "pnpm test"             # hook de verificación
verify  = "pnpm lint && pnpm test"# hook de verificación
qa      = "pnpm e2e"              # hook de verificación
pentest = "pnpm audit"            # hook de verificación

# Vincula un tracker de incidencias para sembrar una sesión desde un ticket.
# Referencia por id un conector registrado en el panel, nunca un secreto. Jira O Linear.
[integrations.jira]
connector = "jira-acme"   # el id del conector que registró tu administrador en el panel
project_key = "PROJ"      # el selector "Execute issue" se limita a este proyecto
  • base_branch: la rama de la que nacen las sesiones nuevas y contra la que se revisan.
  • remote: el remoto que se usa al abrir pull requests.
  • worktrees_path (opcional): cambia el directorio gestionado donde se crean los worktrees de sesión. Por defecto van a ~/Chronos/workspaces/<repo>/, fuera del repositorio y a un clic desde tu carpeta personal.
  • [scripts]: los comandos con nombre de tu proyecto (ver la terminal segura). Viven con el repositorio, así que cualquier cambio pasa por tu revisión normal.
  • [integrations]: vincula un tablero de Jira (connector, project_key, default_jql opcional) o un equipo de Linear (connector, team_key) para arrancar sesiones desde una incidencia. Solo referencia un conector que tu administrador registró en el panel; aquí no vive ninguna credencial. Un workspace vincula un solo tracker: si aparecen las dos secciones, gana Jira.

Hooks de verificación y puerta de merge

Los slots test, verify, qa y pentest son los hooks de verificación: alimentan los Checks de la sesión y la puerta de merge. Un check en rojo bloquea el merge. Ver Pull requests y merge.

Run targets: [[scripts.targets]] (monorepos)

Un repositorio con más de un paquete ejecutable declara un [[scripts.targets]] por unidad, en lugar del slot run plano:

[[scripts.targets]]
id       = "web"                # id estable que usan la interfaz y los workflows
label    = "Web app"            # etiqueta del selector (por defecto, el id)
dir      = "apps/web"           # directorio de trabajo, relativo a la raíz del worktree
setup    = "pnpm install"       # setup por target, corre después del general
run      = "pnpm dev --port $CHRONOS_PORT"
run_mode = "server"
port_env = ["PORT"]             # nombres extra de entorno que reciben el puerto asignado
primary  = true                 # lo que apuntan la terminal, los workflows y el navegador

[[scripts.targets]]
id  = "api"
dir = "services/api"
run = "cargo run"
run_mode = "server"

Cada target corre en su propio directorio y con su propio CHRONOS_PORT, así que web y api pueden estar levantados a la vez sin pisarse. dir tiene que quedarse dentro del worktree: una ruta absoluta o con .. se rechaza y el target degrada a la raíz. Exactamente un target es primary (el que apuntan la terminal, los workflows y el navegador integrado); si ninguno lo marca, gana el primero declarado. Un repositorio sin targets se comporta igual que siempre: los slots planos run/run_mode/setup actúan como un target default implícito. Ver Ejecutar tu proyecto.

¿Nada ejecutable todavía?

El botón Configurar automáticamente del panel Run hace que el agente lea el repositorio (con soporte de monorepos) y genere una propuesta de [scripts]. Queda pendiente e inerte hasta que alguien con el permiso settings.approve la acepta, lo que escribe .chronos/settings.toml en el worktree para que el cambio llegue también al pull request.

Sandbox: [sandbox]

Los ajustes de aislamiento del sistema operativo. Es un control de seguridad, así que esta sección es solo committeada: el fichero local de overrides nunca la lleva.

[sandbox]
egress = "loopback"       # red saliente: "open" (por defecto) o "loopback"
extra_writes = ["~/Library/Developer/Xcode/DerivedData"]
extra_deny_reads = ["~/secrets"]
  • egress: la política de red saliente del sandbox del agente. open (por defecto, los builds llegan a cualquier registro) o loopback (todo denegado salvo el broker local).
  • extra_writes: subárboles extra donde el sandbox puede escribir, además del worktree y las cachés de toolchain incluidas de serie. Útil para un build que escribe una caché que Chronos no trae en su lista curada. Cada ruta debe ser absoluta (un ~/ inicial se expande), vivir bajo tu home o el directorio temporal y no contener ..; lo demás se ignora.
  • extra_deny_reads: subárboles ocultos a lectura además de la lista de credenciales que Chronos ya bloquea. Para secretos guardados en una ruta no estándar que el agente nunca debería leer. Misma validación que extra_writes.

Overrides locales: .chronos/settings.local.toml

Puedes guardar overrides personales de tu máquina que no se comparten con el equipo. Viven en la raíz del workspace (no dentro de un worktree, así persisten entre sesiones) y están en gitignore: nunca llegan al repositorio.

[scripts]
setup    = "npm install --prefer-offline"
run      = "npm run dev -- --port $CHRONOS_PORT"
run_mode = "server"

Del fichero local solo se leen los slots ergonómicos setup, run y run_mode; un valor puesto gana al committeado y uno vacío o ausente cae al del equipo. Los hooks de la puerta de merge (test/verify/qa/pentest) son solo committeados: un fichero local nunca puede debilitar la puerta, aunque los defina. Lo mismo aplica a [sandbox].

En un monorepo esos tres slots también se pueden sobreescribir por target: una entrada [[scripts.targets]] local parchea por id y lleva solo lo que cambias, así que tocar el run de un paquete no altera el dir del equipo ni los demás targets.

[[scripts.targets]]
id  = "web"
run = "pnpm dev --host --port $CHRONOS_PORT"

La capa local está a su vez gobernada: el pack scripts-local-overrides es el interruptor de tu organización sobre ella y se aplica al leer el fichero. Apagar el pack desactiva un settings.local.toml que ya existe, no solo los nuevos.

El puerto por sesión: CHRONOS_PORT

Cuando arrancas la app con el script run, Chronos asigna a cada sesión su propio puerto libre de loopback (en el rango 4100 a 4999) y se lo pasa en la variable de entorno CHRONOS_PORT, de modo que las sesiones paralelas nunca chocan. Haz que tu script lea el puerto que Chronos le da en vez de fijar uno:

[scripts]
run = "pnpm dev --port $CHRONOS_PORT"

Ver Ejecutar tu proyecto.

Configuración de empresa

La gobernanza de tu organización (agentes y herramientas disponibles, estándares y prompts aplicados, quién aprueba y quién mergea) se configura de forma central en el panel corporativo, no en este fichero.