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

# Projects

> Create and manage isolated Polpo Cloud projects

A project is the deployment and isolation boundary in Polpo Cloud. Agents, teams, workflows, files, sessions, project-scoped keys, and usage belong to a project.

## Project resources

Each project has:

* an isolated project database
* a logical sandbox pool for executions
* project-scoped object storage
* a managed model gateway configuration
* a generated 20-character lowercase alphanumeric slug
* a data-plane endpoint at `https://{project-slug}.polpo.cloud`

The display name and generated endpoint slug are separate values. Renaming a project does not turn its name into a DNS label.

## Create with the CLI

The CLI wizard handles login, organization and project selection, scaffolding, key creation, linking, and the first deploy:

```bash theme={null}
npx @polpo-ai/cli create
```

## Create with the API

Project creation is a control-plane operation. Send it to `api.polpo.sh`, authenticated by a dashboard session or a platform-scoped API key:

```bash theme={null}
curl -X POST https://api.polpo.sh/v1/projects \
  -H "Authorization: Bearer $POLPO_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "your-org-id",
    "name": "My Project"
  }'
```

A project-scoped key cannot create another project. Runtime calls use the project's `*.polpo.cloud` endpoint instead of the control-plane URL.

## Link a local directory

```bash theme={null}
npx @polpo-ai/cli link --project-id <uuid>
```

Linking writes the project identifiers to `.polpo/polpo.json`, pulls the current remote resources, and writes project credentials to `.env.local` when that file does not already exist.

## Organization access

Projects belong to an organization. Organization membership and role checks control who can list, read, update, or delete them. API key scopes provide the corresponding boundary for programmatic access.

## Delete a project

Deletion marks the project as deleted and blocks its runtime immediately. It is not an immediate hard delete of every external resource. The cleanup process retains provisioned resources for a recovery window, currently 14 days by default, before purging them.

Do not describe project deletion as instantly reversible or instantly permanent: access stops immediately, while physical cleanup is deferred.