---
title: Your project
description: 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](/docs/work/sessions) branches from it. Every
[change request](/docs/work/change-requests) 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](/docs/connect/connectors), its [triggers](/docs/connect/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](/docs/project/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. |

## In this section

<CardGroup>
  <Card icon="file-text" title="Manifest" href="/docs/project/manifest">The full beeuni.yaml reference.</Card>
  <Card icon="bot" title="Agents" href="/docs/project/agents">Markdown personas with scoped tools.</Card>
  <Card icon="brain" title="Models" href="/docs/project/models">Which model a session uses, and who pays.</Card>
  <Card icon="key" title="Secrets" href="/docs/project/secrets">Encrypted values injected into a sandbox.</Card>
  <Card icon="scroll-text" title="Legacy TOML" href="/docs/project/legacy-toml">Migrating from beeuni.toml.</Card>
</CardGroup>