> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Projects: Organize Agents & Connections

> Group agents, secrets, and app connections into isolated projects. Each project has its own credential pool, dashboard, audit log, and team members.

Projects group your agents, secrets, and app connections into isolated workspaces. The project is the credential pool; each agent uses only what you [grant](/docs/guides/agent-access.md) it from that pool.

## Why projects?

Without projects, everything lives in a flat list. Two teams working on different products draw from the same credential pool. With projects, you create natural boundaries:

* **payments-app**: Stripe agent + Stripe API key
* **ai-assistant**: Claude agent + Anthropic key + Gmail connection
* **staging**: test agents with sandbox credentials

Each project is isolated. An agent in `payments-app` can't see secrets in `ai-assistant`.

## Default project

Every Buckle account starts with a **Default** project. If you only have one use case, you never need to think about projects. Everything goes into Default automatically.

## Creating a project

> [tab] Dashboard
>
> Open **Settings** > **Workspaces** and click **New workspace**. Enter a name and you're done.

> [tab] CLI
>
> ```bash theme={null}
> buckle projects create --name "payments-app"
> ```

## Switching projects

> [tab] Dashboard
>
> Open the **Organization** menu at the bottom of the sidebar and pick a workspace. The agents in the sidebar and everything under **Settings** > **Apps** belong to the active workspace.

> [tab] CLI
>
> Set a default project for all commands:
>
> ```bash theme={null}
> buckle config set project payments-app
> ```
>
> Or pass `--project` to any command:
>
> ```bash theme={null}
> buckle agents list --project payments-app
> buckle secrets list --project staging
> ```

## Renaming a project

> [tab] Dashboard
>
> Open **Settings** > **Workspaces**, choose **Rename** from the workspace's actions menu, and enter the new name.

> [tab] CLI
>
> ```bash theme={null}
> buckle projects update --id proj_abc123 --name "new-name"
> ```

## Running agents in a project

When you run an agent with `buckle run`, the project is resolved from the agent's identity:

```bash theme={null}
buckle run -- claude
```

The agent belongs to a project. The gateway injects the credentials granted to that agent automatically. No `--project` flag needed for `buckle run` because the agent knows which project it's in.

When a project has several agents, choose which one a machine runs as with `buckle config set agent <identifier>` (or `buckle run --agent <identifier>` for a single run). Without either, `buckle run` uses the project's default agent.

## How access works

The project holds the pool: its own secrets and app connections, plus any shared from the organization. Agents in other projects can never reach it — the project is the isolation boundary.

Within the project, access is per agent: an agent uses only the connections and secrets you [grant](/docs/guides/agent-access.md) it, and a connection grant can be narrowed to specific tools with allow and approval lists. On top of that, organization [policy rules](/docs/guides/rules.md) apply as guardrails no project can loosen.

## Plan limits

| | Free | Pro (\$25/mo) | Team (\$20/user/mo) |
| - | - | - | - |
| Projects | 1 | 3 | Unlimited |
| Agents | 2 | 5 included, +\$5/mo per extra | 5/seat, +\$5/mo per extra |
| Secrets | 10 | Unlimited | Unlimited |

Limits are pooled across the organization, not per project.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.