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 structureCopy Anchor Link

The starter is intentionally small:

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.
• 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 projectCopy Anchor Link

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 agentCopy Anchor Link

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 projectCopy Anchor Link

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 projectCopy Anchor Link

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.