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
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
- Dashboard
- CLI
Open Settings > Workspaces and click New workspace. Enter a name and you’re done.
Switching projects
- Dashboard
- CLI
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.
Renaming a project
- Dashboard
- CLI
Open Settings > Workspaces, choose Rename from the workspace’s actions menu, and enter the new name.
Running agents in a project
When you run an agent withbuckle run, the project is resolved from the agent’s identity:
--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 it, and a connection grant can be narrowed to specific tools with allow and approval lists. On top of that, organization policy rules apply as guardrails no project can loosen.Plan limits
Limits are pooled across the organization, not per project.