Manifest reference

Every beeuni.yaml v2 key, with defaults, limits, and validation rules.

The manifest is the file the platform treats as authoritative for a project. This page lists every beeuni.yaml (v2) key, its type, its default, and how the platform validates it. For the plain-language version, see Your project.

Two configuration surfaces

A Beeuni project has two configuration surfaces with strict, non-overlapping ownership.

• Beeuni config — beeuni.yaml at the repo root defines the project environment, agents, tools, connectors, and triggers. Sandbox templates can reference a custom Dockerfile.
• Agent config — the agent files, skills, and harness files. The agent harness reads this, in the sandbox and locally.

Projects created before 2026-09 keep agents and skills under .beeuni/opencode/ and memory under .beeuni/memory/. Beeuni reads both layouts.

The join between the two halves is the agent’s .md file. A manifest key agents.<name> governs the file that agents.<name>.file names, or agents/<name>.md when file is omitted. Every behavioral field lives only in that .md file’s frontmatter and body, never in beeuni.yaml:

• system prompt
• model, mode
• temperature, top_p
• steps, permission

The manifest’s agents: block sets governance only: which agents may launch, and what each one may touch. The validator enforces this. It rejects a v2 agent block that contains any behavioral field, with an error that points at the agent’s own .md file.

Location and versions

Any repo with a valid manifest at its root is a Beeuni project. beeuni.yaml (v2, YAML only) is the current format for new projects, created by the web “Create project” flow and by beeuni init. beeuni.toml (v1) still works for existing projects, but the platform accepts no new v2 features on it. See Legacy TOML for the v1 schema and the v1-to-v2 migration steps.

beeuni_version: 2 requires YAML — a .toml file that declares beeuni_version: 2 fails validation. A manifest that declares a version higher than 2 is rejected outright, so the platform never silently misreads a future field. Unknown top-level keys are ignored, so you can park your own metadata in the file.

validateManifest() is the single gate behind beeuni ship, the change request merge check, and beeuni validate. The same rules apply everywhere, so anything that merges into main is structurally sound. The schema is public and generated from the same package:

• beeuni.v2.schema.json
• beeuni.v1.schema.json
• beeuni.schema.json (dispatches on beeuni_version)

Point a beeuni.yaml at the v2 schema for editor validation, or fetch it from the CLI:

# yaml-language-server: $schema=https://beeuni.ai/schema/beeuni.v2.schema.json
beeuni_version: 2

beeuni schema --version 2

Full example

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.

Top-level keys

imports:

Split one manifest across several YAML files. Use it when beeuni.yaml outgrows one screen: 30 triggers with multi-line prompts, a connector per team, one file per agent group.

# 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

beeuni.yaml
agents.yaml
triggers/
  reports/
    weekly.yaml
    monthly.yaml
  dockets/
    freedom-forever.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.

The root file and its imports form one project configuration. A trigger in one file can name an agent declared in another.

Rules

1. A path is relative to the repository root. .., absolute paths, and globs are rejected.
2. A directory import takes every .yaml and .yml file below it, at any depth, sorted by path. Other files are skipped.
3. An imported file declares triggers, connectors, agents, apps, tools, and imports. Every other key (beeuni_version, default_agent, runtime, project, env, opencode, sandbox, policy, policies) stays in the root file. An imported file that sets one fails validation.
4. An imported file can import more files. The limit is 8 levels and 200 files. A cycle is an error. A file reached twice merges once.
5. One name, one file. A trigger slug, connector slug, agent name, app name, or tool name declared in two files is an error that names both files. Nothing overrides silently.
6. Entries merge in order: the importing file first, then its imports in the order listed.

A broken import fails the whole manifest, the same way a YAML syntax error does. beeuni validate, beeuni ship, and the change request merge check all report it before it reaches main:

imports: triggers "weekly-report" is declared in both triggers/a.yaml and triggers/b.yaml — one name, one file

Edits go to the file that declares the entry. When the dashboard, the API, or beeuni triggers enable|disable|rm changes a trigger, connector, agent, or app that an imported file declares, only that file is written. The root file is not rewritten. A new entry is written to the root file. Move it into an imported file by hand if you want it there.

imports requires beeuni.yaml. A beeuni.toml manifest ignores the key.

tools:

The tools a session gets, by name. A value is one of two forms:

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

The default runtime and experimental runtime run the same module. The module contract, beeuni tools ls, beeuni tools eject, and the migration from harnesses/opencode/tools/ are in Tools.

Selection rule.

• No tools key, in the root file or in any imported file: sessions get all five Beeuni tools. Every project created before the list existed keeps them.
• A tools key, even an empty one (tools: {}, or tools: with every line deleted): sessions get only the Beeuni tools it lists, as beeuni:<name> or as a module path. A tools key in an imported file counts.

Delete a beeuni:<name> line to remove that tool from every agent. Use agents.<name>.tools to limit one agent.

Errors.

• A name is snake_case: ^[a-z][a-z0-9_]{0,63}$.

• A harness tool name (bash, read, write, edit, apply_patch, glob, grep, list, task, question, todowrite, webfetch, websearch, skill, lsp, invalid, execute, plan_exit, pty_*) is an error.

• A path ends in .ts, .js, .mts, .mjs, .cts, or .cjs. It must not start with / or -, or contain a . or .. segment.

• beeuni:<name> under another key is an error. Under a Beeuni tool name, for example web_search: beeuni:image_search:

  tools.web_search: must be `beeuni:web_search` (the Beeuni tool) or a repo-relative path to a .ts or .js module (e.g. `tools/web_search.ts`) that replaces it.

• beeuni:<name> for a name that is not a Beeuni tool, for example web_serch: beeuni:web_serch:

  tools.web_serch: must be a repo-relative path to a .ts or .js module (e.g. `tools/web_serch.ts`). `beeuni:<name>` names a Beeuni tool under its own name: `web_search: beeuni:web_search`, `image_search: beeuni:image_search`, `scrape_webpage: beeuni:scrape_webpage`, `memory: beeuni:memory`, `show: beeuni:show`.

• beeuni validate also reports a declared module that does not exist. A beeuni: value needs no file.

Warnings. A warning never fails beeuni validate.

• A tools key that lists none of the five Beeuni tools:

  tools: Sessions of this project get no Beeuni tool (web_search, image_search, scrape_webpage, memory, show). Add `<name>: beeuni:<name>` to keep one.

  It catches a project that adds its first own tool and drops the five by accident.

• An agent’s tools that names a Beeuni tool the project does not load:

  agents.beeuni.tools: "show" is a Beeuni tool this project does not load: add `show: beeuni:show` under the top-level `tools`, or remove it here.

project:

Optional, human-facing metadata: name and description. The platform does not read this table for anything — a project’s display name comes from its own database record. Treat it as documentation for people reading the repo.

env:

Declares the env var names your sessions need. Values live in the dashboard’s Environment variables page, never inline in the manifest. The platform decrypts and injects them as plain env vars at session start.

env:
  required: [DATABASE_URL]
  optional: [STRIPE_API_KEY]

Env var names match ^[A-Z_][A-Z0-9_]*$. The Secrets Manager caps a name at 64 characters — a longer name parses here but can never get a value. Names starting with BEEUNI_ can never get a value either. Keep names at 64 characters or fewer, and avoid the BEEUNI_ prefix. Full contract: Secrets.

sandbox: and sandbox.templates

A list of named, bootable sandbox images. Optional — with no entries, every session boots the platform’s default image. Each template needs exactly one of dockerfile (repo-relative) or image (a public Docker reference, tag- or digest-pinned).

sandbox:
  templates:
    - slug: ml
      name: ML Development
      dockerfile: Dockerfile.ml
      cpu: 4
      memory: 16
      disk: 50

Each value must be a positive integer. A value below the minimum fails validation with an error. A value above the maximum passes with a warning, then clamps at runtime. GPUs are not supported — declaring gpu produces a warning, not an error. See Runtime for what the runtime layer injects on top of your image.

sandbox.default

Set default on sandbox to make one template the project-wide default. Every session, trigger, and channel then boots it without naming a slug.

sandbox:
  default: dev
  templates:
    - slug: dev
      dockerfile: Dockerfile.dev

default must name a template declared in this manifest, or the reserved value "default" for the platform image.

An agent can select its environment with agents.<name>.sandbox. The value must name a manifest or dashboard template, or "default".

agents:
  researcher:
    sandbox: ml

Session template resolution uses this order:

1. Explicit session sandbox_slug.
2. Selected agent sandbox.
3. Project sandbox.default.
4. Platform "default".

Cron triggers, webhook triggers, schedules, and channels use the selected agent’s template.

A spec change (cpu, memory, disk, container_runtime, or the image itself) rebuilds the project’s snapshot. The new size applies on the next session, not a running one.

opencode:

Where the default runtime config directory lives. Optional, with a default.

opencode:
  config_dir: harnesses/opencode

When config_dir is not set, Beeuni uses the first of harnesses/opencode and .beeuni/opencode that holds an opencode.json or opencode.jsonc. That directory holds the files only the default runtime reads: opencode.jsonc, plugins/, tools/, and commands/. Agents and skills live at the repo root, in agents/ and skills/. opencode.jsonc stays the runtime registry for plugins, MCP servers, providers, and permissions — do not duplicate those settings in the manifest. See Agents.

harnesses:

Per-harness settings. pi.config_dir points to a repository-relative directory of extension runtime configuration (default: harnesses/pi, then .beeuni/pi). The directory is imported on the experimental runtime boot. pi.packages is separate: it installs packages from the manifest’s harnesses.pi.packages per agent. Today one package key exists: pi.packages, the experimental runtime packages every experimental runtime session of this project loads (runtime: pi, or the pi_harness flag). A package can include extensions (tools, hooks, commands), and the skills and prompts a package ships.

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

At most 20 entries. Git sources are rejected.

Per agent

An agent can add its own packages and drop top-level ones, under agents.<name>.harnesses:

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

• An agent’s packages are the top-level list, minus its exclude, plus its own packages.
• An agent entry for a package the top level also lists replaces the top-level entry for that agent (another version, or other filters).
• exclude lists package names (pi-web-access, @scope/name) or ./ paths as the top-level list writes them. It never takes a version.
• Each distinct package list is built once. Agents with the same list share the build.
• Packages belong to the agent a session starts with. A subagent that another agent starts with the task tool uses the standard workspace tools only (bash, read, write, edit, glob, grep), not its own packages and not the parent’s; the parent’s extension hooks still apply to its calls. Start a session with that agent to use its packages.

How packages reach a session:

1. Merging the change request that edits this list builds the packages once, for the sandbox platform, with install scripts off. Each extension is pre-built into one minified file. The build keeps the package’s other files, except the code that file already contains, type declarations, source maps, and the root README and CHANGELOG. Projects with the same list share the build.
2. A new or restarted session downloads the build while its repository clones, and loads each extension directly. A session never runs npm install or compiles a package.
3. A package that cannot be pre-built (for example, one whose pi.extensions uses globs) still works: the session loads it from the installed packages instead, which takes longer. If a package’s code reads one of the files the build leaves out, give its entry an extensions filter: the session then loads it from the installed packages too.
4. A session that starts before the build exists boots without the project packages and starts the build; the next session has them.

Beeuni also installs a set of system packages into every experimental runtime session. A project entry for the same package replaces the system version. A repository can also hold extension runtime extensions in .pi/extensions/*.ts; experimental runtime loads them without a manifest entry.

Extensions run without a terminal UI: tools, hooks, and commands work; terminal-only widgets do nothing.

triggers:

A list of cron, webhook, and monitor definitions. Each entry fires a session that runs prompt as its first message.

triggers:
  - slug: daily-digest
    type: cron
    cron: '0 0 9 * * 1-5'
    prompt: Summarize yesterday's commits.

Cron triggers need exactly one of cron (a 6-field expression) or run_at (a one-off ISO-8601 timestamp), plus timezone as an IANA name. Webhook triggers need secret_env, the name of a secret that uses broker delivery with the connector consumer. Monitor triggers need run (a repo-relative command) and mode (poll or stream), and reject every cron and webhook field. Full field reference, credential setup, payload templating, endpoints, and session strategy: see Triggers.

connectors:

A list of external tools an agent can call. The definition lives in git; credentials live in the platform, never in the manifest. See Connectors for the conceptual model.

connectors:
  - slug: gmail-read
    name: Gmail read only
    provider: pipedream
    app: gmail
    authorization_strategy: user
    policies:
      - match: search_email
        action: always_run

Provider-specific fields:

channel connectors rarely need a hand-written entry — connecting a channel from the dashboard creates one for you. See Slack & channels. The slugs beeuni_slack, beeuni_teams, beeuni_email, and computer are platform-owned; using one with a different provider is a validation error. The computer connector is created when the first member connects a computer, because machine ids are account control-plane identities and must not enter the manifest.

connectors.auth: optional, for providers other than pipedream. type is bearer, basic, custom, api_key, oauth1, hmac, aws_sigv4, mtls, or none (default). oauth1 is restricted to openapi, postman, and http providers. in is header (default), query, or cookie. name is required when type is custom or api_key.

connectors.policies: a list of {match, action} pairs. match is a glob over tool names. action is always_run, require_approval, or block. Policies belong to the connector. Every connection under that connector uses the same policies.

policy.default_mode: a top-level key, separate from connectors:, that sets the project-wide connector approval mode. It takes allow_all (default; every unmatched tool runs) or risk (require approval for write and destructive unmatched calls). Set it with beeuni connectors policy set --default <risk|allow_all> — see CLI.

Channels

v2 removes channels: from the schema. Channel-to-agent routing (Slack, Microsoft Teams, email, and voice today) is live operational state, not declarative config. You set it from the dashboard’s Channels page or from chat commands, the same boundary that keeps credentials out of git. Connecting a channel still creates a connectors entry with provider: channel for the agent to call. See Slack & channels. The v1 [[channels]] table is covered in Legacy TOML.

agents:

A name-to-block map, keyed by agent name. This map is governance only — it grants what an agent may touch, never what it says or does.

This block is the second of the two bindings: a principal gets roles from Beeuni, and an agent additionally carries the Beeuni permissions declared here. A session can only do what both allow. See One vocabulary, two bindings.

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]

v2 is deny-by-default: an omitted connectors, secrets, beeuni_permissions, skills, or apps on a declared agent resolves to none. Grant every permission an agent needs explicitly, as the starter’s beeuni agent does above. A project migrating from v1 must re-grant everything by hand — v1 defaults env (secrets) to all when omitted, the opposite of v2.

connectors_personal remains a deprecated input alias for connectors_required. New manifests must use connectors_required. The connector’s authorization_strategy decides whether the authorization is project-owned or member-owned.

beeuni_permissions grants come from a fixed set of project-scoped permissions (project.read, project.gitops.push, project.gitops.merge, project.gitops.ref.any, project.trigger.*, project.secret.*, project.connector.*, and more). Account-scoped permissions — member.*, billing.*, project.create — can never be granted to an agent. Run beeuni validate --scopes from inside a session to print the live, grantable list.

The agent file

agents.<name>.file names the agent’s .md, relative to the repo root.

agents:
  support:
    file: agents/support.md

• The path must end in .md.
• The path must not start with / or -. It must not contain a . or .. segment, or an empty segment.
• Each segment uses only letters, digits, _, -, ., and spaces.
• When file is omitted, Beeuni reads agents/<name>.md, then .beeuni/opencode/agents/<name>.md. With opencode.config_dir set, the second path is <config_dir>/agents/<name>.md.
• When the dashboard saves an agent that has a .md, it writes file with that path.
• The API refuses a request that changes file (400, code invalid_config). To move an agent, move its .md and update file in beeuni.yaml in the same commit.

beeuni validate and the change request merge check reject an invalid file with an error on agents.<name>.file.

When config changes take effect

• A manifest, agents/, skills/, or default runtime config directory edit applies only after a change request merges to main. Sessions and triggers read the default branch, not session branches.
• A trigger’s cron or webhook change is picked up by the scheduler within seconds of the merge.
• A sandbox image or hardware change rebuilds the snapshot. The new spec applies on the next session, not the current one.
• A secret value change in the dashboard resolves at sandbox-create time. It applies on the next session, not a running one.

Round-trip rules

Dashboard edits are a read-modify-write on the file that declares the entry: beeuni.yaml, or an imported file. To keep diffs clean across UI and in-session edits:

1. Keep beeuni_version as the first key.
2. Inside a trigger entry, order fields slug, name, type, agent, enabled, then type-specific fields, then prompt last.
3. If you add a webhook trigger before its secret is set, list the secret name in env.optional. Leave the trigger enabled: false until the value is in.

Repository access

Set agents.<name>.repository_access to false for agents that do not need project source files. They can still create sandbox files and use their granted tools, secrets, and connectors. Set it to true for agents that need the repository. Git permissions remain separate. Change this setting in the agent editor under Workspace → Project repository access. The setting applies to new sessions. Existing sessions keep their saved policy, including after runtime replacement.

agents:
  support:
    repository_access: false
  engineer:
    repository_access: true

The deprecated workspace field remains readable: branch means true, and runtime means false. Legacy read configurations still reject session creation until you replace the field with an explicit boolean. There is no read-only repository mode. Conflicting old and new fields are rejected. The editor and SDK send repository_access. For disabled access, the API also stores workspace: runtime as a compatibility mirror. This preserves the restriction for older API replicas during rollout or rollback. API reads omit the mirror. Hand-authored manifests using only repository_access require the updated API.