# Your project

A project is a git repository that holds your agent's config and state.

Canonical page: https://singulacomp.ai/docs/project

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.

SingulaComp backs a project two ways:

- **SingulaComp-managed repo** — SingulaComp creates and hosts a private repo. Default.
- **Imported GitHub repo** — connect an existing repo. SingulaComp 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 — SingulaComp 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, `singulacomp.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, SingulaComp CLI 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 `singulacomp.toml` (`singulacomp_version: 1`). SingulaComp
reads both formats. See [legacy TOML](/docs/project/legacy-toml) for the
migration path.

## In this section

- [Manifest](/docs/project/manifest): The full singulacomp.yaml reference.
- [Agents](/docs/project/agents): Markdown personas with scoped tools.
- [Models](/docs/project/models): Which model a session uses, and who pays.
- [Secrets](/docs/project/secrets): Encrypted values injected into a sandbox.
- [Legacy TOML](/docs/project/legacy-toml): Migrating from singulacomp.toml.