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

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.

A session starts from `default_branch` unless its creation request supplies `base_ref`. 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.

<a id="the-manifest"></a>

## The manifest

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.

## 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">Agent behavior · Grants and permissions</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>