Deployments and environments

Understand development, production, immutable deployments, and aliases

A deployment is an immutable build of one agent. An alias gives a stable name to the deployment clients should run.

New projects have one environment, default. Every deploy creates an immutable deployment and makes it the current one; sessions keep the deployment they were admitted with. Use separate projects when you need distinct development and production targets.

Projects created before single-environment mode are legacy projects with two working environments:

Environment	Alias	How it changes
Development	development	npm run deploy -- --watch publishes source changes
Production	production	An explicit deploy advances it

Sessions keep the deployment they started with. Publishing another version does not change the code underneath an existing session.

Deploy to production (legacy projects)

From the project directory:

npm run deploy -- --alias production

Every deploy first runs opencomputer doctor, a local static scan for invalid connection origins, misplaced tools, and missing secret declarations, and then prints the project it resolved and the cloud id each local agent deploys as. Run opencomputer doctor --json directly to get structured diagnostics, with the same resolution under resolution, before invoking a deployment agent.

The CLI builds the current source, creates an immutable deployment, and moves the production alias to it. Development remains available for further work.

Select an agent and environment

Clients identify an agent with agent-id@alias:

support@development
support@production

Single-environment projects use bare agent-id (or agent-id@default); older clients sending agent-id@development resolve to the same deployment, while agent-id@production is rejected with single_environment_project. Explicit --environment and --alias flags are rejected for these projects; link persists the project and --project overrides it for one command.

Legacy project dashboards keep the environment selector to change which deployment you are inspecting. The playground has a separate agent selector when a project contains more than one agent.

Review history

Open the project’s Deployments page to inspect immutable versions, their aliases, and creation times. Use the deployment ID when correlating a session with logs or the debug inspector.