Your project
A project is a git repository that holds your agent's config and state.
A project is one git repository. It holds a manifest, agent config, and the state your agent produces. No separate database exists to keep in sync.
Beeuni backs a project two ways:
- Beeuni-managed repo — Beeuni creates and hosts a private repo. Default.
- Imported GitHub repo — connect an existing repo. Beeuni operates on it through the GitHub API.
Either way, the project has a default_branch. Every
session branches from it. Every
change request merges into it. Each branch of a
GitHub repo can become its own project. main and dev can then run as
separate projects, each with its own sessions and change requests.
A project is not your codebase
A project holds your agent’s instructions, its connectors, its triggers, and its memory. Keep it small — Beeuni clones it into every session.
Your code lives elsewhere. When a task needs a codebase, the agent clones that repository, does the work, and opens a change request back to it. Do not turn an existing codebase into a project by adding a manifest to it. Create a dedicated project instead, and point it at the repositories the agent works on.
The manifest
Every project has a manifest at its repo root, beeuni.yaml by default. The
platform reads these top-level keys:
| Key | Configures |
|---|---|
default_agent |
which agent runs by default |
agents |
per-agent grants: connectors, secrets, skills, Beeuni permissions |
sandbox |
the sandbox image and hardware |
triggers |
scheduled and webhook automation |
connectors |
which external tools the project can reach |
env |
env variable names the project expects (values come from secrets) |
Unknown keys are ignored.
Older projects may still run beeuni.toml (beeuni_version: 1). Beeuni
reads both formats. See legacy TOML for the
migration path.
Deleting a project
Delete a project with Delete project under Danger zone in its
settings, or with beeuni projects rm. From that moment, nothing can act for
the project:
| Way in | After the delete |
|---|---|
LLM gateway keys (kgw_…) |
Refused with 401. |
| Public share links | Answer 410. |
| Apps | Not served. |
| New sessions | Refused: 404, code: "project_archived". |
| Slack and Teams | Reply “This Beeuni workspace was deleted…” and start nothing. |
| Email inboxes | Reply once to the first email of a thread: “This address is not accepting email right now. No one will answer this message.” The next reply in that thread within 30 days gets nothing, and email that fails sender authentication never gets a reply. |
| Existing sessions | Take no new message: not from a chat thread, a trigger, or a prompt queued before the delete. |