Projects and agents

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:

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
└── package.json

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

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:

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:

opencomputer/agents/researcher/agent.ts

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:

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
Memory for reading, editing and exporting saved agent notes
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.

Getting started

Concepts

Agent API

Test and operate

Examples

Project structure

Create or select the cloud project

Add another agent

Inspect the project

​Project structure

​Create or select the cloud project

​Add another agent

​Inspect the project

Project structure

Create or select the cloud project

Add another agent

Inspect the project