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

# Projects and agents

> Organize multiple cloud agents and a React application

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

## Project structure

The starter is intentionally small:

```text theme={null}
my-agent/
├── opencomputer/
│   ├── .env.example
│   ├── project.ts
│   ├── channels/        # optional project messaging channels
│   ├── outboxes/        # optional durable notification routes
│   └── agents/
│       └── hello-world/
│           ├── agent.ts
│           ├── channels/    # optional inbound registrations
│           ├── outboxes/    # optional publish registrations
│           ├── tools/       # optional
│           ├── skills/      # optional
│           └── schedules/   # optional
├── src/
│   ├── App.tsx
│   └── main.tsx
├── package.json
└── vite.config.ts
```

* `opencomputer/project.ts` declares project metadata and agent IDs.
* `opencomputer/agents/<id>/agent.ts` defines one agent.
* `opencomputer/channels/` and `opencomputer/outboxes/` define shared project
  resources; registrations under an agent authorize that agent to use them.
* `opencomputer/.env.local` optionally holds ignored development secrets.
* `src/` is a normal React application.
* `.opencomputer/` is ignored local state created by the CLI.

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. `npm create` writes local
source. Link it to a cloud project with:

```bash theme={null}
npx --package @opencomputer/cli opencomputer link
```

The command asks whether to create a project or select an existing one. If you
skip it, the first project-scoped command shows the same prompt.

For non-interactive use:

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

Later commands reuse `.opencomputer/project.json`. Run `opencomputer link`
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
* **Channels** for environment-specific Slack installation and destination
  binding
* **Outboxes** for inspecting proactive notification delivery
* **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.