Manifest reference

Configure agents, skills, tools and permissions in beeuni.yaml.

New projects use beeuni_version: 2. Agent behavior lives in agents/<name>.md (frontmatter and prompt); access grants live in agents.<name> 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

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-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.

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.<name> 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.

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:<name> values: built-in tools need no entry.

Tools

Commands

A command is a saved prompt invoked as /<name>. 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.

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:<package>@<exact-version> 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.

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.

# 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

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 <connector>.<tool> using globs, with actions such as always_run, require_approval and block. See 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.

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.

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.

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.

approvals:
  ttl: 4h

Agents and permissions · Tools · Models · Secrets · Connectors · Triggers · Apps