opencomputer CLI—and the same agent project can run locally or in a managed
sandbox.
The layers
Agent project
The project is the portable definition of the agent. Its committed files describe:- stable UUID and readable display name in
opencomputer.toml - behavior and approval rules in
instructions.md - runtime and model configuration
- tools and skills
- required connections and channels
- initial workspace files and evaluations
OpenComputer CLI
The CLI owns the developer workflow:- discover templates
- initialize a complete project
- authenticate the developer
- authorize managed connections
- run the project locally with OpenCode
- package and deploy the project
- start sessions from deployed agents
opencomputer deploy, the CLI builds a canonical source artifact
from the agent directory and sends it to OpenComputer. Infrastructure provider
details are not part of the CLI contract.
Agent identity and deployments
The UUID inopencomputer.toml identifies the agent across its lifetime. Its
two-word name is display metadata and can change without creating a different
agent. Each distinct source artifact becomes an immutable deployment.
production provide a stable target while preserving the
exact source behind every deployment. Deploying unchanged source is
idempotent; deploying changed source creates a new version.
Managed sessions and sandboxes
A deployed run creates a managed session from the selected agent version. OpenComputer prepares an isolated sandbox, loads the agent source and workspace, starts OpenCode, and streams the result back to the CLI. The sandbox is an implementation detail of the agent experience. You do not need to create or manage a separate sandbox before deploying an agent. Each session has:- the exact deployed source version
- an isolated filesystem and process environment
- a workspace that the agent can use during the task
- access to only the connections and channels declared for that agent
- lifecycle management handled by OpenComputer
Connections
Connections let agent tools act on services such as Gmail without committing OAuth tokens to Git. For Gmail:1
Declare
The template places a Google connection declaration in
connections/google.json.2
Authorize
opencomputer connection add gmail --alias personal opens the account
authorization flow. Add another alias to connect another Gmail account.3
Develop locally
The CLI gives the local agent a short-lived, scoped route to the managed
connection.
4
Run when deployed
The managed session receives the same connection capability inside its
sandbox. Provider credentials remain outside the project and agent output.
Connections and aliases
Learn how connection declarations, user identity, and multiple accounts work.
Local and deployed execution
This symmetry is intentional: develop the actual agent locally, then deploy
the same directory instead of rebuilding the workflow in a dashboard.
Managed sessions can be listed, inspected, attached to, resumed with another
turn, and ended from the CLI. A session is the durable unit of interaction;
the sandbox runtime may suspend between turns and resume when needed.
Deployment sequence
Security boundaries
- Agent source and identity are reviewable and commit-friendly.
- OAuth credentials are managed separately from source code.
- Local connection access uses a scoped session capability.
- Deployed agents run inside isolated sandboxes.
- The public CLI and API do not expose infrastructure-provider credentials or storage implementation details.
- Consequential actions should remain behind explicit instructions and user approval.
Deploy a Gmail summarizer
Follow the complete CLI workflow.