> ## Documentation Index
> Fetch the complete documentation index at: https://opensandbox-feat-types-open-question-labels.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Projects and agents

> Organize multiple cloud agents in one project

A project is the cloud boundary for related agents, environments, deployments,
and sessions. A source repository contains the project's agent definitions.

## Project structure

The starter is intentionally small:

```text theme={null}
my-agent/
├── opencomputer/
│   ├── .env.example
│   ├── project.ts
│   ├── database/        # optional default database migrations
│   └── agents/
│       └── hello-world/
│           ├── agent.ts
│           ├── tools/       # optional
│           ├── skills/      # optional
│           └── schedules/   # optional
└── package.json
```

* `opencomputer/project.ts` declares project metadata and agent IDs.
* `opencomputer/agents/<id>/agent.ts` defines one agent.
* `opencomputer/database/migrations/` holds ordered SQL migrations for the
  project's [default database](/agents/database).
* `opencomputer/.env.local` optionally holds ignored development secrets.
* `.opencomputer/project.json` records the linked cloud project; the CLI's
  build output is cached under `node_modules/.cache/opencomputer/` and never
  lands in `opencomputer/`.

Add source files only when the project uses them. The starter does not generate
placeholder capability directories.

## Create or select the cloud project

The source scaffold and cloud project are separate. `opencomputer init` writes
local source. Link it to a cloud project with:

```bash theme={null}
npx --package @opencomputer/cli opencomputer link --project <project-id-or-slug>
# Or create one explicitly:
npx --package @opencomputer/cli opencomputer link --create-project "Support agents"
```

There is no project picker. If you skip linking, project-scoped commands return
a structured `binding_required` error with the explicit command to run.

You can also link as part of a watched deploy:

```bash theme={null}
npx --package @opencomputer/cli opencomputer deploy --watch --project <project-id-or-slug>
npx --package @opencomputer/cli opencomputer deploy --watch --create-project "Support agents"
```

Later commands reuse `.opencomputer/project.json`. Run `opencomputer link` with
an explicit selector again when you intentionally want this source directory
to target another project.

## Add another agent

Create a new agent module:

```text theme={null}
opencomputer/agents/researcher/agent.ts
```

```tsx theme={null}
import { useModel } from "@opencomputer/agent";

export default function Agent() {
  useModel("anthropic/claude-sonnet-4.6");
  return "Research the request, verify claims, and cite useful sources.";
}
```

Then list it in `opencomputer/project.ts`:

```tsx theme={null}
export default {
  name: "Customer workspace",
  agents: ["hello-world", "researcher"],
};
```

The running development process synchronizes both agents. In the dashboard,
the project-level environment selector switches between `development` and
`production`; the playground has a separate agent selector.

## Inspect the project

The current project dashboard provides:

* **Agent playground** for creating and resuming test sessions
* **Deployments** for immutable version history and active aliases
* **Sessions** created through the dashboard, React client, or API
* **Schedules** deployed from each agent's source directory
* **Memory** for reading, editing and exporting saved agent notes
* **Database** for inspecting tables, rows and applied migrations, and running
  read-only queries
* **Secrets** for write-only project and agent credentials

Project and agent behavior remains code-owned. The dashboard is for selection,
inspection, and testing. Use `opencomputer logs` to diagnose agent and
outbound-request failures.

## Archive and restore a project

Archive a project from the Projects page when you no longer want it active.
Archiving stops running sessions and prevents new deployments, sessions,
schedules, Slack turns, and webhook deliveries. It preserves the project's
agents, deployment history, secrets, connections, and other configuration.

Archived projects remain available in the **Archived** section. Select
**Restore** to return one to the active project list with its configuration
intact.


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