--- title: "Manifest reference" description: "Configure agents, skills, tools and permissions in beeuni.yaml." --- New projects use `beeuni_version: 2`. Agent behavior lives in `agents/.md` (frontmatter and prompt); access grants live in `agents.` in `beeuni.yaml`. The dashboard agent editor edits v2. Version 3 remains available for manually authored projects; its behavior lives in the manifest and the dashboard shows those agents read-only. ## v2: the default for new projects ```yaml beeuni_version: 2 default_agent: assistant agents: assistant: file: agents/assistant.md connectors: all secrets: all skills: all beeuni_permissions: all ``` ## v3 reference (manually authored projects) ## Example ```yaml # yaml-language-server: $schema=https://beeuni.ai/schema/beeuni.v3.schema.json beeuni_version: 3 default_agent: assistant env: required: [ORDERS_API_KEY] skills: triage: skills/triage tools: lookup_order: tools/lookup_order.ts commands: summarize: description: Summarize a ticket. prompt: Summarize $ARGUMENTS in five bullets. extensions: audit: opencode: extensions/audit.opencode.ts pi: extensions/audit.pi.ts agents: assistant: description: Answers support questions. mode: primary prompt_file: agents/assistant.md permission: bash: ask tools: all skills: [triage, beeuni-connectors] subagents: [researcher] commands: [summarize] extensions: [audit] secrets: [ORDERS_API_KEY] beeuni_permissions: [project.session.read, project.review.submit] researcher: mode: subagent prompt: Look up orders and report the facts. Never modify an order. tools: [lookup_order, read, grep, web_search] secrets: [ORDERS_API_KEY] ``` ## Registries A registry gives a resource a name; it does not grant access. Register project skills, tools, commands and extensions at the top level. Agent grants refer to these names. Beeuni tools and managed skills need no registry entry. ```text skills name → folder tools name → module.ts commands name → { description?, prompt | prompt_file } extensions name → { opencode?, pi? } connectors [{ slug, provider, ... }] apps slug → App configuration triggers [{ slug, type, agent?, ... }] ``` ## Agent behavior An agent has a prompt, a model, tool rules and resource grants. In v3, they live in one `agents.` block in `beeuni.yaml`. Use `prompt` for inline text or `prompt_file` for a Markdown prompt, never both. Behavior keys include `description`, `mode`, `model`, `variant`, `temperature`, `top_p`, `steps`, `options`, `color`, `hidden`, `enabled` and `permission`. `mode` is `primary`, `subagent` or `all` (default). `enabled: false` disables the agent. The default agent must be enabled and support primary sessions. ## Grants and permissions Omitted `skills`, `subagents`, `commands`, `extensions`, `connectors`, `secrets`, `apps` and `beeuni_permissions` grant nothing. Use `all`, `none` or a list of names. An omitted `tools` means every available tool; an omitted `permission` means `allow`. `tools` controls which tools the model sees. `permission` controls whether a visible tool call runs (`allow`), waits for approval (`ask`) or is refused (`deny`). File and shell rules can match patterns. In v3, do not set `permission.skill` or `permission.task`: use `skills` and `subagents`. Connector access, secret access and Beeuni project permissions are separate grants. An agent uses its own permissions, capped by its assigned role; starting it does not give it your role. Grants come from the default branch, so an agent cannot widen its access by editing its session branch. ## Skills A skill is a folder containing `SKILL.md`. Register the folder under `skills`; its final path segment and the frontmatter `name` must match the registry key. An unregistered project skill is not visible. The `beeuni-` prefix belongs to managed skills. Grant those by name, such as `beeuni-memory` or `beeuni-connectors`, or use `skills: all`. ```yaml skills: triage: skills/triage agents: assistant: skills: [triage, beeuni-memory] ``` ## Register a tool A tool name uses snake_case, up to 64 characters. Do not use a harness tool name or the `pty_` prefix. A module path is repository-relative and ends in `.ts`, `.js`, `.mts`, `.mjs`, `.cts` or `.cjs`. V3 rejects `beeuni:` values: built-in tools need no entry. [Tools](/docs/project/tools) ## Commands A command is a saved prompt invoked as `/`. Set exactly one of `prompt` and `prompt_file`. `$ARGUMENTS` inserts all arguments; `$1`, `$2`, and later placeholders insert positional arguments. Commands run on the selected agent and have no `agent` key. An agent that does not enable a command receives `403` with `command_not_enabled`. ```yaml commands: summarize: description: Summarize a ticket. prompt: Summarize $ARGUMENTS in five bullets. agents: assistant: commands: [summarize] ``` ## Extensions An extension registers an OpenCode plugin, a pi extension/package, or both. Enable it in each agent that needs it. Use a repository module for `opencode`; `pi` also accepts `npm:@` or a source object with `extensions`, `skills`, `prompts` and `themes` filters. Version ranges and git sources are invalid. An omitted filter loads all; `[]` loads none. Extensions load when a session starts; switching agents keeps the initial extensions. ```yaml extensions: audit: opencode: extensions/audit.opencode.ts pi: extensions/audit.pi.ts agents: assistant: extensions: [audit] ``` ## Subagents Only declared agents run. A parent lists its allowed delegates under `subagents`; each delegate must have `mode: subagent` or `all`. Declaring an agent does not let every other agent call it. The built-in OpenCode agent names are disabled unless the manifest declares them. ## Imports Imports accept repository-relative YAML files or directories. Directory imports read every `.yaml` and `.yml` below them. Import only manifest files: other YAML, such as an app package configuration, can fail validation. Paths stay relative to the repository root, even inside an imported file. Duplicate names, cycles, more than 8 levels or more than 200 files are errors. Imported files may contain `agents`, `skills`, `tools`, `commands`, `extensions`, `connectors`, `apps`, `triggers` and `imports`. Keep the other project-wide keys in the root file. Paths cannot be absolute or contain `.` or `..` segments. ```yaml # beeuni.yaml beeuni_version: 3 default_agent: assistant imports: - agents/ - skills/skills.yaml - tools/tools.yaml - commands/commands.yaml - extensions/extensions.yaml - connectors/ - apps/apps.yaml - triggers/ ``` ## Secrets `env.required` and `env.optional` list secret names, never values. Store values in project Secrets and grant each agent only the names it needs. Missing required values prompt you in the dashboard and `beeuni ship`; they do not block session startup. [Secrets](/docs/project/secrets) ## Sandbox templates With no sandbox template, sessions use the platform image. A template has a unique `slug` and exactly one of `image` (with a tag or digest) and `dockerfile` (repository path). Optional fields are `name`, `entrypoint`, `cpu` (1–32 vCPU), `memory` (1–128 GiB), `disk` (1–500 GiB) and `container_runtime`. Select with `sandbox.default` or an agent’s `sandbox`. Hardware changes apply to new sessions. ## Runtime New sessions run pi. Existing OpenCode sessions remain supported. The manifest field `runtime` is deprecated and no longer selects a harness. V3 uses the manifest rather than repository harness folders. Put plugins and packages under `extensions`, and enable them per agent. `codemode: on | only | off` affects pi only. ## Connector approvals Connector approval rules are separate from tool permissions. `policy.default_mode: allow_all` runs unmatched calls; `risk` allows reads and asks for writes or destructive actions. `policies` match `.` using globs, with actions such as `always_run`, `require_approval` and `block`. See [Connectors](/docs/connect/connectors). ## Validation Validate before merging. The v3 validator rejects unknown keys, unresolved grants, invalid names and paths, and a missing, disabled or subagent-only default agent. `file` and `disable` on an agent, and top-level `opencode`, `pi`, `harnesses` or `permission`, belong to older formats and are invalid in v3. Use `prompt_file`, `enabled`, `extensions` and per-agent `permission` instead. ```bash beeuni validate beeuni validate --file beeuni.yaml --json beeuni validate --scopes beeuni schema --version 3 ``` ## Legacy versions Version 1 (`beeuni.toml`) still runs and can be upgraded to v2 from Customize → Upgrades. Versions 2 and 3 require YAML. There is no automatic v2-to-v3 upgrade. Validate manually authored v3 changes before merging. See [Legacy TOML](/docs/project/legacy-toml). ## When changes take effect Merge configuration changes into the project’s default branch. New sessions use them, and running sessions pick up supported changes through configuration reload. A new agent cannot run before its declaration reaches the default branch. See [Runtime](/docs/work/runtime#config-convergence). ## Approval expiry `approvals.ttl` controls how long a connector call waits for a decision. Use an integer followed by `m`, `h` or `d`, such as `30m`, `4h` or `7d`. Beeuni limits the value to 5 minutes–30 days. The default is `24h`; invalid values also use that default. ```yaml approvals: ttl: 4h ``` [Agents and permissions](/docs/project/agents) · [Tools](/docs/project/tools) · [Models](/docs/project/models) · [Secrets](/docs/project/secrets) · [Connectors](/docs/connect/connectors) · [Triggers](/docs/connect/triggers) · [Apps](/docs/apps)