--- title: "Referencia del manifiesto" description: "Cada clave de beeuni.yaml v2, con valores predeterminados, límites y reglas de validación." --- La plataforma considera que el manifiesto es la fuente de verdad de un proyecto. Esta página enumera todas las claves `beeuni.yaml` (v2), su tipo, su valor predeterminado y cómo las valida la plataforma. Para una explicación en lenguaje sencillo, consulta [Tu proyecto](/docs/es/project). ## Dos superficies de configuración Un proyecto de Beeuni tiene dos superficies de configuración con responsabilidades estrictas y sin superposición. - **Configuración de Beeuni** — `beeuni.yaml` en la raíz del repositorio define el entorno del proyecto, los agentes, las herramientas, los conectores y los activadores. Las plantillas de sandbox pueden hacer referencia a un Dockerfile personalizado. - **Configuración del agente** — los archivos del agente, las habilidades y los archivos del harness. El harness del agente la lee, tanto en el sandbox como localmente. | Ruta | Qué contiene | | --- | --- | | `beeuni.yaml` | El manifiesto: agentes y a qué puede acceder cada uno, activadores, conectores, env y plantillas de sandbox. | | `agents/.md` | Un agente: frontmatter y prompt del sistema. `agents..file` lo nombra. | | `skills//SKILL.md` | Una habilidad. Todos los harnesses la cargan. | | `memory/` | La memoria del proyecto. | | `tools/.ts` | Herramientas del proyecto, un módulo por herramienta. `tools:` las declara; todos los harnesses las ejecutan. Consulta [Herramientas](/docs/es/project/tools). | | `harnesses/opencode/` | Archivos que solo lee harness estándar: `opencode.jsonc`, `plugins/`, `tools/`, `commands/`. `opencode.config_dir` apunta aquí. | Los proyectos creados antes de 2026-09 conservan los agentes y las habilidades en `.beeuni/opencode/` y la memoria en `.beeuni/memory/`. Beeuni lee ambas estructuras. La unión entre las dos partes es el archivo `.md` del agente. Una clave del manifiesto `agents.` rige el archivo que nombra `agents..file`, o `agents/.md` si se omite `file`. Todos los campos de comportamiento se encuentran únicamente en el frontmatter y el cuerpo de ese archivo `.md`, nunca en `beeuni.yaml`: - prompt del sistema - `model`, `mode` - `temperature`, `top_p` - `steps`, `permission` El bloque `agents:` del manifiesto establece únicamente la gobernanza: qué agentes pueden iniciarse y qué puede tocar cada uno. El validador hace cumplir estas reglas. Rechaza los bloques de agente v2 que contienen campos de comportamiento e indica en el error el archivo `.md` del propio agente. ## Ubicación y versiones Cualquier repositorio con un manifiesto válido en su raíz es un proyecto de Beeuni. `beeuni.yaml` (v2, solo YAML) es el formato actual para proyectos nuevos, creados mediante el flujo web «Create project» y mediante `beeuni init`. `beeuni.toml` (v1) sigue funcionando para los proyectos existentes, pero la plataforma no admite funciones nuevas de v2 en esta versión. Consulta [TOML heredado](/docs/es/project/legacy-toml) para ver el esquema v1 y los pasos de migración de v1 a v2. `beeuni_version: 2` requiere YAML: un archivo `.toml` que declara `beeuni_version: 2` no supera la validación. Se rechaza sin más un manifiesto que declara una versión superior a `2`, para que la plataforma nunca interprete silenciosamente de forma incorrecta un campo futuro. Las claves desconocidas de nivel superior se ignoran, así que puedes guardar tus propios metadatos en el archivo. `validateManifest()` es la única puerta de control tras `beeuni ship`, la comprobación de combinación de solicitudes de cambio y `beeuni validate`. Se aplican las mismas reglas en todas partes, de modo que todo lo que se combine en `main` tenga una estructura válida. El esquema es público y se genera desde el mismo paquete: - [`beeuni.v2.schema.json`](/schema/beeuni.v2.schema.json) - [`beeuni.v1.schema.json`](/schema/beeuni.v1.schema.json) - [`beeuni.schema.json`](/schema/beeuni.schema.json) (se selecciona según `beeuni_version`) Apunta un `beeuni.yaml` al esquema v2 para validar en el editor, o consíguelo mediante la CLI: ```yaml # yaml-language-server: $schema=https://beeuni.ai/schema/beeuni.v2.schema.json beeuni_version: 2 ``` ```bash beeuni schema --version 2 ``` ## Ejemplo completo ```yaml beeuni_version: 2 default_agent: beeuni project: name: my-project description: What this project is. env: required: [DATABASE_URL] optional: [STRIPE_API_KEY, WEBHOOK_SLACK_SECRET] sandbox: templates: - slug: ml name: ML Development dockerfile: Dockerfile.ml cpu: 4 memory: 16 opencode: config_dir: harnesses/opencode agents: beeuni: file: agents/beeuni.md connectors: all secrets: all beeuni_permissions: all skills: all release-bot: file: agents/release-bot.md sandbox: ml connectors: [github] beeuni_permissions: [project.gitops.push] secrets: [GITHUB_AGENT_TOKEN] triggers: - slug: daily-digest type: cron agent: beeuni cron: '0 0 9 * * 1-5' timezone: America/Los_Angeles prompt: | Summarize yesterday's commits. Open a CR against main. ``` ## Claves de nivel superior | Clave | Obligatoria | Notas | | --------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------ | | `beeuni_version` | sí | debe ser `2` | | `default_agent` | sí | debe nombrar un agente declarado y habilitado | | `imports` | no | otros archivos YAML o directorios cuyos `triggers`, `connectors`, `agents`, `apps` y `tools` se combinan con este manifiesto. Consulta [`imports:`](#imports) | | `tools` | no | las herramientas que recibe cada sesión: nombre de herramienta → ruta del módulo relativa al repositorio, o `beeuni:` para una herramienta de Beeuni. Si hay una clave `tools`, las sesiones reciben únicamente las herramientas de Beeuni que enumera. Todos los harnesses las ejecutan. Consulta [`tools:`](#tools) | | `runtime` | no | `"opencode"` (predeterminado) o `"pi"`: el harness del agente que inicia una sesión dentro de su sandbox; `pi` ejecuta harness experimental en el proceso dentro del daemon del sandbox y lee los mismos archivos `.md` del agente y las mismas habilidades. La marca de función `pi_harness` del proyecto selecciona harness experimental sin esta línea. harness experimental necesita la marca `llm_gateway`; sin ella, la sesión inicia harness estándar. | | `harnesses.pi.packages` | no | paquetes de harness experimental que cargan las sesiones harness experimental del proyecto. Consulta [`harnesses:`](#harnesses) | | `pi.config_dir` | no | `harnesses/pi` y, después, `.beeuni/pi` si está presente. `settings.json`, `extensions/`, `skills/` y `prompts/` nativos de harness experimental. | | `project.name` / `project.description` | no | metadatos de visualización; la plataforma no lee `project.name` para obtener el nombre que se muestra del proyecto | | `env.required` / `env.optional` | no | nombres de variables de entorno; `required` es solo orientativo y nunca se exige al iniciar la sesión | | `sandbox` / `sandbox.templates` / `sandbox.default` | no | imagen o imágenes del sandbox y hardware | | `opencode.config_dir` | no | `harnesses/opencode` predeterminado y, después, `.beeuni/opencode` heredado | | `triggers` | no | lista de activadores cron, webhook y monitor | | `connectors` | no | lista de definiciones de conectores | | `policy.default_mode` | no | `allow_all` (predeterminado) o `risk`; modo de aprobación de conectores para todo el proyecto | | `agents` | sí | mapa de gobernanza de nombre a bloque; no debe estar vacío. Con `imports`, el mapa puede estar en un archivo importado | ## `imports:` Divide un manifiesto entre varios archivos YAML. Úsalo cuando `beeuni.yaml` ya no quepa en una sola pantalla: 30 activadores con prompts de varias líneas, un conector por equipo o un archivo por grupo de agentes. ```yaml # beeuni.yaml beeuni_version: 2 default_agent: beeuni imports: - triggers/ # a directory: every .yaml and .yml file below it - agents.yaml # a single file agents: beeuni: connectors: all ``` ```text beeuni.yaml agents.yaml triggers/ reports/ weekly.yaml monthly.yaml dockets/ freedom-forever.yaml ``` ```yaml # triggers/reports/weekly.yaml triggers: - slug: weekly-report name: Cross-Sector Weekly Report type: cron agent: galileo cron: "0 15 * * 0" prompt: |- Build the weekly report. ``` El archivo raíz y sus importaciones forman una configuración de proyecto. Un activador de un archivo puede nombrar un agente declarado en otro. **Reglas** 1. Una ruta es relativa a la raíz del repositorio. Se rechazan `..`, las rutas absolutas y los patrones glob. 2. Una importación de directorio toma todos los archivos `.yaml` y `.yml` que haya debajo, a cualquier profundidad, ordenados por ruta. Los demás archivos se omiten. 3. Un archivo importado declara `triggers`, `connectors`, `agents`, `apps`, `tools` y `imports`. Todas las demás claves (`beeuni_version`, `default_agent`, `runtime`, `project`, `env`, `opencode`, `sandbox`, `policy`, `policies`) permanecen en el archivo raíz. Si un archivo importado define una de ellas, la validación falla. 4. Un archivo importado puede importar otros archivos. El límite es de 8 niveles y 200 archivos. Los ciclos generan un error. Si se llega a un archivo dos veces, se combina una sola vez. 5. Un nombre, un archivo. Si un slug de activador, un slug de conector, un nombre de agente, un nombre de app o un nombre de herramienta se declara en dos archivos, se produce un error que indica ambos archivos. Nada se sobrescribe de forma silenciosa. 6. Las entradas se combinan en orden: primero, el archivo que importa y, después, sus importaciones en el orden indicado. Una importación con errores invalida todo el manifiesto, igual que un error de sintaxis YAML. `beeuni validate`, `beeuni ship` y la comprobación de combinación de la solicitud de cambio informan del error antes de que llegue a `main`: ```text imports: triggers "weekly-report" is declared in both triggers/a.yaml and triggers/b.yaml — one name, one file ``` **Los cambios se escriben en el archivo que declara la entrada.** Cuando el dashboard, la API o `beeuni triggers enable|disable|rm` modifica un activador, un conector, un agente o una app declarado en un archivo importado, solo se escribe en ese archivo. El archivo raíz no se vuelve a escribir. Las entradas nuevas se escriben en el archivo raíz. Si quieres que una entrada quede en un archivo importado, muévela allí manualmente. `imports` requiere `beeuni.yaml`. Un manifiesto `beeuni.toml` ignora la clave. ## `tools:` Las herramientas que recibe una sesión, por nombre. Un valor tiene una de estas dos formas: | Forma | Significado | | --- | --- | | `beeuni:` | Una herramienta de Beeuni (`web_search`, `image_search`, `scrape_webpage`, `memory`, `show`), mantenida por Beeuni. La clave debe ser ``. | | Una ruta de módulo relativa al repositorio | Una herramienta propia del proyecto, en cualquier carpeta. Si usa el nombre de una herramienta de Beeuni, el módulo la reemplaza. | ```yaml tools: web_search: beeuni:web_search image_search: beeuni:image_search scrape_webpage: beeuni:scrape_webpage memory: tools/memory.ts # replaces the Beeuni memory tool lookup_order: tools/lookup_order.ts crm_note: integrations/crm/note.ts ``` harness estándar y harness experimental ejecutan el mismo módulo. El contrato del módulo, `beeuni tools ls`, `beeuni tools eject` y la migración desde `harnesses/opencode/tools/` están en [Tools](/docs/es/project/tools). **Regla de selección.** - Si no hay ninguna clave `tools`, ni en el archivo raíz ni en ningún archivo importado, las sesiones reciben las cinco herramientas de Beeuni. Todos los proyectos creados antes de que existiera la lista las conservan. - Si hay una clave `tools`, aunque esté vacía (`tools: {}` o `tools:` con todas las líneas eliminadas), las sesiones reciben solo las herramientas de Beeuni que incluya, como `beeuni:` o como ruta de módulo. También cuenta una clave `tools` en un archivo importado. Elimina una línea `beeuni:` para quitar esa herramienta de todos los agentes. Usa [`agents..tools`](/docs/es/project/tools#who-may-use-which-tool) para limitarla a un solo agente. **Errores.** - Los nombres deben estar en snake_case: `^[a-z][a-z0-9_]{0,63}$`. - Un nombre de herramienta del entorno de ejecución (`bash`, `read`, `write`, `edit`, `apply_patch`, `glob`, `grep`, `list`, `task`, `question`, `todowrite`, `webfetch`, `websearch`, `skill`, `lsp`, `invalid`, `execute`, `plan_exit`, `pty_*`) genera un error. - Una ruta termina en `.ts`, `.js`, `.mts`, `.mjs`, `.cts` o `.cjs`. No debe empezar por `/` ni `-`, ni contener un segmento `.` o `..`. - `beeuni:` bajo otra clave genera un error. Bajo el nombre de una herramienta de Beeuni, por ejemplo `web_search: beeuni:image_search`: ```text tools.web_search: debe ser `beeuni:web_search` (la herramienta de Beeuni) o una ruta relativa al repositorio a un módulo .ts o .js (p. ej., `tools/web_search.ts`) que la reemplace. ``` - `beeuni:` para un nombre que no sea de una herramienta de Beeuni, por ejemplo `web_serch: beeuni:web_serch`: ```text tools.web_serch: debe ser una ruta relativa al repositorio a un módulo .ts o .js (p. ej., `tools/web_serch.ts`). `beeuni:` nombra una herramienta de Beeuni con su propio nombre: `web_search: beeuni:web_search`, `image_search: beeuni:image_search`, `scrape_webpage: beeuni:scrape_webpage`, `memory: beeuni:memory`, `show: beeuni:show`. ``` - `beeuni validate` también informa de un módulo declarado que no existe. Un valor `beeuni:` no requiere un archivo. **Advertencias.** Una advertencia nunca invalida `beeuni validate`. - Una clave `tools` que no incluya ninguna de las cinco herramientas de Beeuni: ```text tools: Las sesiones de este proyecto no reciben ninguna herramienta de Beeuni (web_search, image_search, scrape_webpage, memory, show). Añade `: beeuni:` para conservar una. ``` Esto detecta los casos en que un proyecto añade su primera herramienta propia y elimina las cinco por accidente. - El valor `tools` de un agente que nombre una herramienta de Beeuni que el proyecto no carga: ```text agents.beeuni.tools: "show" es una herramienta de Beeuni que este proyecto no carga: añade `show: beeuni:show` en el elemento `tools` del nivel superior o elimínala aquí. ``` ## `project:` Metadatos opcionales dirigidos a las personas: `name` y `description`. La plataforma no consulta esta tabla para nada; el nombre visible del proyecto procede de su propio registro en la base de datos. Considérala documentación para quienes consulten el repositorio. ## `env:` Declara los nombres de las variables de entorno que necesitan tus sesiones. Los valores se guardan en la página Environment variables del dashboard, nunca directamente en el manifiesto. Al iniciar la sesión, la plataforma los descifra y los inyecta como variables de entorno normales. ```yaml env: required: [DATABASE_URL] optional: [STRIPE_API_KEY] ``` | Campo | Tipo | Notas | | ---------- | ---------- | -------------------------------------------------------------------------------------------------------- | | `required` | `string[]` | Orientativo. El dashboard solicita estos valores al usuario, pero el inicio de la sesión no se bloquea si falta alguno. | | `optional` | `string[]` | Disponibles para las sesiones si se configuran. No pasa nada si faltan. | Los nombres de las variables de entorno deben coincidir con `^[A-Z_][A-Z0-9_]*$`. Secrets Manager limita los nombres a 64 caracteres; aquí se puede analizar un nombre más largo, pero nunca podrá recibir un valor. Los nombres que empiezan por `BEEUNI_` tampoco pueden recibir un valor. Limita los nombres a 64 caracteres y evita el prefijo `BEEUNI_`. Contrato completo: [Secrets](/docs/es/project/secrets). ## `sandbox:` y `sandbox.templates` Una lista de imágenes de sandbox con nombre que se pueden iniciar. Es opcional: si no hay entradas, todas las sesiones se inician con la imagen predeterminada de la plataforma. Cada plantilla debe tener exactamente uno de estos campos: `dockerfile` (relativo al repositorio) o `image` (una referencia pública de Docker, con la etiqueta o el digest fijados). ```yaml sandbox: templates: - slug: ml name: ML Development dockerfile: Dockerfile.ml cpu: 4 memory: 16 disk: 50 ``` | Campo | Tipo | Predeterminado | Notas | | ------------ | ------ | -------------------------- | --------------------------------------------------------------------------------- | | `slug` | string | — | Obligatorio. Único por proyecto. `default` está reservado. | | `name` | string | slug | Etiqueta que se muestra en el selector del panel. | | `dockerfile` | string | — | Ruta relativa al repositorio. Mutuamente excluyente con `image`. | | `image` | string | — | Imagen pública de Docker, fijada por etiqueta o digest. Mutuamente excluyente con `dockerfile`. | | `entrypoint` | string | propia de la capa de runtime | Reemplaza el entrypoint del contenedor. | | `cpu` | int | predeterminado del proveedor | Núcleos de vCPU. Límite: 1–32. | | `memory` | int | predeterminado del proveedor | RAM en GiB. Límite: 1–128. | | `disk` | int | predeterminado del proveedor | Disco en GiB. Límite: 1–500. | | `container_runtime` | bool | `false` | Ejecuta Docker en el sandbox con redes bridge y overlay. Consulta [Runtime](/docs/es/work/runtime#docker-in-the-sandbox). | Cada valor debe ser un entero positivo. Un valor inferior al mínimo hace que la validación falle con un error. Un valor superior al máximo pasa con una advertencia y luego se limita en runtime. Las GPU no son compatibles; declarar `gpu` produce una advertencia, no un error. Consulta [Runtime](/docs/es/work/runtime) para saber qué inyecta la capa de runtime sobre tu imagen. ### `sandbox.default` Establece `default` en `sandbox` para convertir una plantilla en la predeterminada para todo el proyecto. Cada sesión, activador y canal la inicia sin especificar un slug. ```yaml sandbox: default: dev templates: - slug: dev dockerfile: Dockerfile.dev ``` `default` debe nombrar una plantilla declarada en este manifiesto o el valor reservado `"default"` para la imagen de la plataforma. Un agente puede seleccionar su entorno con `agents..sandbox`. El valor debe nombrar una plantilla del manifiesto o del panel, o `"default"`. ```yaml agents: researcher: sandbox: ml ``` La resolución de la plantilla de sesión usa este orden: 1. `sandbox_slug` de sesión explícito. 2. `sandbox` del agente seleccionado. 3. `sandbox.default` del proyecto. 4. `"default"` de la plataforma. Los activadores cron, los activadores de webhook, las programaciones y los canales usan la plantilla del agente seleccionado. Un cambio en la especificación (`cpu`, `memory`, `disk`, `container_runtime` o la propia imagen) vuelve a generar la instantánea del proyecto. El nuevo tamaño se aplica en la siguiente sesión, no en una que ya esté en ejecución. ## `opencode:` Dónde se encuentra el directorio de configuración de harness estándar. Opcional, con un valor predeterminado. ```yaml opencode: config_dir: harnesses/opencode ``` | Campo | Tipo | Predeterminado | Notas | | ------------ | ------ | ------------------------------------------------------ | ------------------------ | | `config_dir` | string | `harnesses/opencode`, luego `.beeuni/opencode` | Directorio relativo al repositorio. | Cuando no se establece `config_dir`, Beeuni usa el primero de `harnesses/opencode` y `.beeuni/opencode` que contenga un `opencode.json` o `opencode.jsonc`. Ese directorio contiene únicamente los archivos que lee harness estándar: `opencode.jsonc`, `plugins/`, `tools/` y `commands/`. Los agentes y las skills se encuentran en la raíz del repositorio, en `agents/` y `skills/`. `opencode.jsonc` sigue siendo el registro nativo de harness estándar para plugins, servidores MCP, proveedores y permisos; no dupliques esos ajustes en el manifiesto. Consulta [Agents](/docs/es/project/agents). ## `harnesses:` Configuración por harness. `pi.config_dir` apunta a un directorio relativo al repositorio que contiene configuración nativa de harness experimental (predeterminado: `harnesses/pi`, luego `.beeuni/pi`). El directorio se importa al iniciar harness experimental. `pi.packages` es independiente: instala paquetes del `harnesses.pi.packages` del manifiesto para cada agente. Actualmente existe una clave de paquete: `pi.packages`, los paquetes de harness experimental que carga cada sesión de harness experimental de este proyecto (`runtime: pi` o la marca `pi_harness`). Un paquete puede ser cualquier cosa de packages: extensiones (herramientas, hooks y comandos), además de las skills y los prompts que incluya el paquete. ```yaml runtime: pi harnesses: pi: packages: - npm:pi-web-access@0.30.0 # pinned extension version - source: npm:pi-mcp-adapter@2.36.0 extensions: ["extensions/*.ts"] # load only these files of the package skills: [] # load none of its skills - ./harnesses/pi/audit.ts # an extension file in this repository ``` | Forma de entrada | Significado | | --- | --- | | `npm:@` | Un paquete npm en una versión exacta. Un rango o una versión ausente hace que la validación falle. | | `./` | Un archivo de extensión o directorio de paquete en este repositorio. No puede salir del repositorio con `..`. | | `{ source, extensions, skills, prompts, themes }` | La misma fuente con los filtros propios de inclusión/exclusión de harness experimental. Si se omite el filtro, se carga todo; `[]` no carga nada. | Como máximo, 20 entradas. Las fuentes de Git se rechazan. ### Por agente Un agente puede añadir sus propios paquetes y excluir paquetes de nivel superior mediante `agents..harnesses`: ```yaml harnesses: pi: packages: [npm:pi-web-access@0.30.0] # every agent agents: researcher: harnesses: pi: packages: [npm:@juicesharp/rpiv-todo@2.11.0] # researcher only reviewer: harnesses: pi: exclude: [pi-web-access] # reviewer loads no web tools ``` - Los paquetes de un agente son la lista de nivel superior menos su `exclude`, más sus propios `packages`. - La entrada de un agente para un paquete que también aparece en el nivel superior reemplaza la entrada de nivel superior para ese agente (otra versión u otros filtros). - `exclude` enumera nombres de paquetes (`pi-web-access`, `@scope/name`) o rutas `./` tal como aparecen en la lista de nivel superior. Nunca incluye una versión. - Cada lista de paquetes distinta se compila una vez. Los agentes con la misma lista comparten la compilación. - Los paquetes pertenecen al agente con el que se inicia una sesión. Un subagente que otro agente inicia con la herramienta `task` usa únicamente las herramientas estándar del espacio de trabajo (`bash`, `read`, `write`, `edit`, `glob`, `grep`), no sus propios paquetes ni los del agente principal; los hooks de extensión del agente principal siguen aplicándose a sus llamadas. Inicia una sesión con ese agente para usar sus paquetes. Cómo llegan los paquetes a una sesión: 1. Al fusionar la solicitud de cambio que edita esta lista, los paquetes se compilan una vez para la plataforma de sandbox, con los scripts de instalación desactivados. Cada extensión se precompila en un único archivo minificado. La compilación conserva los demás archivos del paquete, excepto el código que ese archivo ya contiene, las declaraciones de tipos, los mapas de origen y los archivos README y CHANGELOG raíz. Los proyectos con la misma lista comparten la compilación. 2. Una sesión nueva o reiniciada descarga la compilación mientras clona su repositorio y carga cada extensión directamente. Una sesión nunca ejecuta `npm install` ni compila un paquete. 3. Un paquete que no se puede precompilar (por ejemplo, uno cuyo `pi.extensions` usa patrones glob) sigue funcionando: la sesión lo carga desde los paquetes instalados, lo que tarda más. Si el código de un paquete lee uno de los archivos que la compilación excluye, añade un filtro `extensions` a su entrada; la sesión también lo cargará desde los paquetes instalados. 4. Una sesión que se inicia antes de que exista la compilación arranca sin los paquetes del proyecto e inicia la compilación; la siguiente sesión ya los tendrá. Beeuni también instala un conjunto de paquetes del sistema en cada sesión de harness experimental. Una entrada del proyecto para el mismo paquete reemplaza la versión del sistema. Un repositorio también puede contener extensiones nativas de harness experimental en `.pi/extensions/*.ts`; harness experimental las carga sin una entrada en el manifiesto. Las extensiones se ejecutan sin una interfaz de terminal: las herramientas, los hooks y los comandos funcionan; los widgets exclusivos de terminal no hacen nada. ## `triggers:` Una lista de definiciones de cron, webhook y monitorización. Cada entrada inicia una sesión que ejecuta `prompt` como su primer mensaje. ```yaml triggers: - slug: daily-digest type: cron cron: '0 0 9 * * 1-5' prompt: Summarize yesterday's commits. ``` | Campo | Obligatorio | Predeterminado | Notas | | -------------- | --------------------- | --------------------- | ----------------------------------------------------------------------------------------------------- | | `slug` | sí | — | `[a-z0-9][a-z0-9_-]{0,127}`, único entre los activadores. | | `type` | sí | — | `cron`, `webhook` o `monitor` (experimental). | | `prompt` | sí | — | No puede estar vacío. Admite plantillas. | | `name` | no | slug | Etiqueta legible. | | `agent` | no | `default_agent` | Debe indicar una clave de `agents:`. Omítelo para usar `default_agent`; no escribas el literal `default`. | | `enabled` | no | `true` | `false` omite la entrada. | | `model` | no | se resuelve al activarse | Forma de cable `provider/model`. Fija la sesión activada a ese modelo. Consulta [Modelos](/docs/es/project/models). | | `session_mode` | no | `fresh` | `fresh`, `reuse`, `pinned` o `keyed`. | | `session_id` | obligatorio para `pinned` | — | Sesión exacta a la que volver a enviar la solicitud. | Los activadores cron necesitan exactamente uno de `cron` (una expresión de 6 campos) o `run_at` (una marca de tiempo ISO-8601 única), además de `timezone` como nombre IANA. Los activadores de webhook necesitan `secret_env`, el nombre de un secreto que use la entrega `broker` con el consumidor `connector`. Los activadores de monitor necesitan `run` (un comando relativo al repositorio) y `mode` (`poll` o `stream`), y rechazan todos los campos cron y webhook. Consulta [Activadores](/docs/es/connect/triggers) para obtener la referencia completa de campos, la configuración de credenciales, las plantillas de cargas útiles, los endpoints y la estrategia de sesión. ## `connectors:` Una lista de herramientas externas que puede usar un agente. La definición reside en git; las credenciales, en la plataforma, nunca en el manifiesto. Consulta [Conectores](/docs/es/connect/connectors) para conocer el modelo conceptual. ```yaml connectors: - slug: gmail-read name: Gmail read only provider: pipedream app: gmail authorization_strategy: user policies: - match: search_email action: always_run ``` | Campo | Obligatorio | Notas | | ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `slug` | sí | `[a-z0-9][a-z0-9_-]{0,127}`, único entre los conectores. | | `provider` | sí | `pipedream`, `mcp`, `openapi`, `postman`, `graphql`, `http` o `channel`. | | `name` | no | Nombre visible. De forma predeterminada, es el slug. | | `authorization_strategy` | no | `project` o `user`. Si se omite, el valor predeterminado es `project`. Una estrategia de proyecto usa las conexiones activas del proyecto. Una estrategia de usuario usa solo la conexión del miembro que actúa. | | `enabled` | no | De forma predeterminada, es `true`. | | `credential` | no | Solo se admite `shared`. El modo retirado `per_user` genera un error irrecuperable. | | `sensitive` | no | De forma predeterminada, es `false`. `true` convierte `require_approval` en el valor predeterminado para las acciones sin coincidencia, incluidas las lecturas. Las reglas explícitas de proyecto y conector siguen teniendo prioridad. | Campos específicos de cada proveedor: | Proveedor | Campo obligatorio | Notas | | ----------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `pipedream` | `app` | `account` es opcional; de forma predeterminada, es el slug. | | `mcp` | `url` | `transport`: `http` (predeterminado) o `sse`. | | `openapi` | `spec` | Una URL o una ruta relativa al repositorio. | | `postman` | `spec` | Una URL o ruta de Collection JSON, un manifiesto `.postman/api` o la URL de un espacio de trabajo de Postman. | | `graphql` | `endpoint` | `spec` es opcional (SDL). | | `http` | `base_url` | `spec` es opcional. | | `channel` | `platform` | `slack`, `teams`, `email` o `voice`. | | `computer` | — | Gestionado por la API. No se puede declarar manualmente. Cada ordenador conectado es una de sus cuentas. Consulta [Ordenadores](/docs/es/connect/computers). | Los conectores `channel` rara vez necesitan una entrada escrita a mano: al conectar un canal desde el panel, se crea uno automáticamente. Consulta [Slack y canales](/docs/es/connect/slack). Los slugs `beeuni_slack`, `beeuni_teams`, `beeuni_email` y `computer` pertenecen a la plataforma; usarlos con otro proveedor produce un error de validación. El conector `computer` se crea cuando el primer miembro conecta un ordenador, porque los identificadores de máquina son identidades del plano de control de la cuenta y no deben incluirse en el manifiesto. `connectors.auth`: opcional, para proveedores distintos de `pipedream`. `type` es `bearer`, `basic`, `custom`, `api_key`, `oauth1`, `hmac`, `aws_sigv4`, `mtls` o `none` (predeterminado). `oauth1` está restringido a los proveedores `openapi`, `postman` y `http`. `in` es `header` (predeterminado), `query` o `cookie`. `name` es obligatorio cuando `type` es `custom` o `api_key`. `connectors.policies`: una lista de pares `{match, action}`. `match` es un patrón glob que coincide con nombres de herramientas. `action` es `always_run`, `require_approval` o `block`. Las políticas pertenecen al conector. Todas las conexiones de ese conector usan las mismas políticas. `policy.default_mode`: una clave de nivel superior, independiente de `connectors:`, que establece el modo de aprobación de conectores para todo el proyecto. Acepta `allow_all` (predeterminado; se ejecutan todas las herramientas que no coinciden) o `risk` (requiere aprobación para las llamadas no coincidentes de escritura y destructivas). Configúrala con `beeuni connectors policy set --default ` — consulta [CLI](/docs/es/cli). ## Canales La v2 elimina `channels:` del esquema. El enrutamiento de canales a agentes (por ahora, Slack, Microsoft Teams, correo electrónico y voz) es estado operativo activo, no configuración declarativa. Se configura desde la página Canales del panel o mediante comandos de chat; este mismo límite mantiene las credenciales fuera de git. Al conectar un canal, se sigue creando una entrada `connectors` con `provider: channel` para que el agente la use. Consulta [Slack y canales](/docs/es/connect/slack). La tabla `[[channels]]` de la v1 se describe en [TOML heredado](/docs/es/project/legacy-toml). ## `agents:` Un mapa de nombres a bloques, indexado por nombre de agente. Este mapa sirve únicamente para gobernanza: concede lo que un agente puede tocar, nunca lo que dice o hace. Este bloque es **el segundo de los dos vínculos**: una identidad recibe roles de Beeuni, y además un agente lleva los permisos de Beeuni declarados aquí. Una sesión solo puede hacer lo que ambos permitan. Consulta [Un vocabulario, dos vínculos](/docs/es/accounts#one-vocabulary-two-bindings). ```yaml default_agent: beeuni agents: beeuni: file: agents/beeuni.md connectors: all secrets: all beeuni_permissions: all skills: all release-bot: file: agents/release-bot.md connectors: [github] connectors_required: [github] beeuni_permissions: [project.gitops.push] secrets: [GITHUB_AGENT_TOKEN] ``` | Campo | Valor predeterminado | Notas | | --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | _(clave del mapa)_ | — | `[a-z0-9][a-z0-9_-]{0,127}`, único por proyecto. Si no se especifica `file`, también es el nombre del archivo `.md`. | | `file` | `agents/.md` | Ruta relativa al repositorio del `.md` del agente. Consulta [El archivo del agente](#the-agent-file). | | `enabled` | `true` | `false` trata el agente como no declarado: la plataforma no lo iniciará. | | `connectors` | `none` | Qué slugs de conectores puede usar este agente. `all` significa todos los conectores. | | `connectors_required` | `none` | Obsoleto: se analiza y se ignora. Ya nada impide iniciar el entorno aislado si falta un conector; una llamada a un conector que no tiene nada conectado devuelve `connector_not_connected` con un enlace para conectarlo. Si está presente, debe seguir siendo un subconjunto de `connectors`. | | `secrets` | `none` | Qué secretos del proyecto recibe este agente como variables de entorno del entorno aislado. Renombrado de `env` en la v1. | | `beeuni_permissions` | `none` | Qué permisos de Beeuni (acciones del proyecto) puede ejercer este agente mediante CLI, API o git. `all` significa todos los permisos del proyecto, pero siguen limitados por el rol máximo del agente y nunca incluyen permisos exclusivos para humanos. `beeuni_cli` es la forma obsoleta: todavía se acepta, con una advertencia de validación; establecer ambas con valores distintos es un error. | | `skills` | `none` | Qué habilidades puede cargar este agente. | | `apps` | `none` | Qué slugs de Beeuni App puede abrir este agente cuando la App es `restricted` o `private`. `all` significa todas las Apps del proyecto. Consulta [Agentes y Apps](/docs/es/feature-flags/apps#agents-and-apps). | | `tools` | `all` | Qué herramientas puede usar este agente: del entorno de ejecución, de Beeuni y del proyecto. `all`, `none`, una lista (solo esas) o `{ exclude: [...] }` (todas excepto esas). La forma de mapa anterior `{ bash: false }` sigue funcionando. A diferencia de las concesiones anteriores, si se omite `tools` se permiten todas las herramientas. Consulta [Quién puede usar cada herramienta](/docs/es/project/tools#who-may-use-which-tool). | | `repository_access` | `true` | Indica si las sesiones nuevas reciben el repositorio del proyecto. `false` desactiva la entrega del repositorio y el acceso a este mediante las credenciales de sesión. Las sesiones existentes conservan la política guardada. | La v2 deniega por defecto: si se omite `connectors`, `secrets`, `beeuni_permissions`, `skills` o `apps` en un agente declarado, se resuelve como `none`. Concede explícitamente todos los permisos que necesite el agente, como hace el agente `beeuni` de la plantilla anterior. Los proyectos que migren desde la v1 deben volver a conceder todo manualmente: en la v1, si se omite `env` (secretos), su valor predeterminado es `all`, lo contrario que en la v2. `connectors_personal` sigue siendo un alias de entrada obsoleto para `connectors_required`. Los manifiestos nuevos deben usar `connectors_required`. El valor `authorization_strategy` del conector determina si la autorización pertenece al proyecto o al miembro. Las concesiones `beeuni_permissions` provienen de un conjunto fijo de permisos con alcance de proyecto (`project.read`, `project.gitops.push`, `project.gitops.merge`, `project.gitops.ref.any`, `project.trigger.*`, `project.secret.*`, `project.connector.*`, entre otros). Los permisos con alcance de cuenta —`member.*`, `billing.*`, `project.create`— nunca se pueden conceder a un agente. Ejecuta `beeuni validate --scopes` desde una sesión para mostrar la lista actualizada de permisos que se pueden conceder. ### El archivo del agente `agents..file` indica el `.md` del agente, relativo a la raíz del repositorio. ```yaml agents: support: file: agents/support.md ``` - La ruta debe terminar en `.md`. - La ruta no debe comenzar con `/` ni `-`. No debe contener ningún segmento `.` o `..`, ni segmentos vacíos. - Cada segmento solo puede contener letras, dígitos, `_`, `-`, `.` y espacios. - Si se omite `file`, Beeuni lee `agents/.md` y luego `.beeuni/opencode/agents/.md`. Si se establece `opencode.config_dir`, la segunda ruta es `/agents/.md`. - Cuando el panel guarda un agente que tiene `.md`, escribe `file` con esa ruta. - La API rechaza una solicitud que cambie `file` (`400`, código `invalid_config`). Para mover un agente, mueve su `.md` y actualiza `file` en `beeuni.yaml` en la misma confirmación. `beeuni validate` y la comprobación de fusión de solicitudes de cambio rechazan cualquier `file` no válido, con un error en `agents..file`. ## Cuándo surten efecto los cambios de configuración - Una edición del manifiesto, `agents/`, `skills/` o del directorio de configuración de harness estándar solo se aplica cuando una solicitud de cambio se integra en `main`. Las sesiones y los activadores leen la rama predeterminada, no las ramas de sesión. - El scheduler detecta los cambios de cron o webhook de un activador segundos después de la integración. - Un cambio en la imagen del sandbox o en el hardware reconstruye la instantánea. La nueva configuración se aplica en la siguiente sesión, no en la actual. - Un cambio en el valor de un secreto en el panel se resuelve al crear el sandbox. Se aplica en la siguiente sesión, no en una que ya esté en ejecución. ## Reglas de ida y vuelta Las ediciones del panel realizan una operación de lectura, modificación y escritura en el archivo que declara la entrada: `beeuni.yaml` o un [archivo importado](#imports). Para mantener limpios los diffs entre las ediciones en la interfaz y durante la sesión: 1. Mantén `beeuni_version` como primera clave. 2. Dentro de una entrada de activador, ordena los campos así: `slug`, `name`, `type`, `agent`, `enabled`; después, los campos específicos del tipo; y deja `prompt` para el final. 3. Si añades un activador de webhook antes de definir su secreto, incluye el nombre del secreto en `env.optional`. Deja el activador en `enabled: false` hasta que se introduzca el valor. ### Acceso al repositorio Establece `agents..repository_access` en `false` para los agentes que no necesiten los archivos de código fuente del proyecto. Aun así, podrán crear archivos en el sandbox y usar las herramientas, los secretos y los conectores que se les hayan concedido. Establécelo en `true` para los agentes que necesiten el repositorio. Los permisos de Git se mantienen por separado. Cambia esta configuración en el editor del agente, en **Workspace → Project repository access**. La configuración se aplica a las sesiones nuevas. Las sesiones existentes conservan la política guardada, incluso después de sustituir el entorno de ejecución. ```yaml agents: support: repository_access: false engineer: repository_access: true ``` El campo obsoleto `workspace` sigue siendo legible: `branch` significa `true` y `runtime` significa `false`. Las configuraciones heredadas `read` siguen impidiendo crear sesiones hasta que se sustituya el campo por un valor booleano explícito. No existe un modo de solo lectura para el repositorio. Se rechazan los campos antiguos y nuevos cuando entran en conflicto. El editor y el SDK envían `repository_access`. Si el acceso está deshabilitado, la API también almacena `workspace: runtime` como réplica de compatibilidad. Esto conserva la restricción para las réplicas antiguas de la API durante los despliegues o las reversiones. Las lecturas de la API omiten la réplica. Los manifiestos escritos a mano que solo usan `repository_access` requieren la versión actualizada de la API.