OAT in Cursor Cloud

Cursor Cloud is a harness environment for the same repository-rooted OAT workflow used locally. Cloud context does not change project artifact formats, gate ownership, or autonomy boundaries.

The oat-cursor-cloud-projects orientation skill owns cloud-specific setup and routing guidance. It should surface when OAT is used in a Cursor Cloud environment, and it can also be invoked explicitly. Use oat-project-autonomous separately when the user explicitly requests an end-to-end autonomous run; being in Cursor Cloud does not activate autonomy by itself.

Terms used on this page:

Active project: the OAT project a checkout currently points to, stored as activeProject in that repository's .oat/config.local.json.
Synced project: a project whose artifacts live on a separate Git ref instead of on the feature branch. oat project pull brings them into a checkout, and oat project push publishes changes.
Dispatch: launching a worker or reviewer subagent on a chosen model and route. The dispatch policy is the project's rule for which models those subagents may use; see Dispatch Policy.
User scope: OAT skills, scripts, and config installed in your home directory (for example ~/.oat/config.json) rather than in the repository.

Resolve the project home first

All tracked project artifacts belong to a repository, not to the workspace container or user home.

Multi-repository workspace

Identify the primary repository whose branch, commits, and final PR own the requested work.
Run OAT from that repository root.
Keep the project under that repository's configured projects root, normally <primary-repo>/.oat/projects/shared/<project>/.
Keep checkout-specific state such as activeProject in the primary repository's .oat/config.local.json.
Treat sibling repositories as research or integration context unless the approved plan explicitly assigns them work. Do not create a workspace-level .oat directory to coordinate multiple repositories.

For cross-repository work, choose one primary repository as the artifact and provenance anchor. Record external repository assumptions and evidence in its project artifacts rather than splitting one OAT project across unrelated workspace roots.

Single-repository workspace

The checked-out repository is the project home. Run OAT at its root and use its .oat/ tree exactly as in a local checkout. Do not introduce multi-repository path assumptions.

In both layouts, never store tracked projects under ~/.oat/projects, a workspace aggregator such as /workspace/.oat, or another repository merely because it also contains OAT assets.

Orientation and cloud detection

The orientation skill confirms cloud context from environment markers and, when available, Cursor Cloud run metadata. Run metadata is also the preferred source for the current model family; model self-report is not dispatch evidence.

If cloud metadata is unavailable, the skill degrades to verified environment signals and reports the missing evidence. It does not invent run identity or block repository-local OAT work that otherwise has the required tooling.

Provisioning expectations

A ready cloud environment provides:

the latest published OAT CLI on PATH;
OAT packs and skills installed at user scope;
user-level ~/.oat/config.json defaults for the dispatch candidate ladder and gate execution targets, with availability probes;
cursor-agent installed for configured headless routes;
headless authentication supplied from a Cloud Agents secret;
repository-local config overrides only where a specific repository needs cloud behavior that differs from its shared config.

Provisioning must be idempotent and must not require an open-agent-toolkit source checkout. A practical readiness pass verifies at least:

oat --version
oat config dump
cursor-agent --version

It also verifies that required user-scope packs are present, configured gate targets resolve or degrade through their availability probes, and the harness auth probe succeeds. A missing optional gate CLI may permit a documented degraded route. A required route with no adequate fallback is a boundary.

Secrets stay in the environment or the platform's secret broker. Never write CURSOR_API_KEY or another credential into OAT config, project artifacts, dispatch records, prompts, logs, or the VM image.

User-scope asset precedence

In provisioned cloud environments, the user-scope installation is the execution source for skills and scripts. The user tier is refreshed from the published package during environment setup; repository copies of skills and scripts are compatibility context, not an override.

Templates are the exception. They resolve repository, then user, then bundled, the same order as everywhere else, because a repository template is an owner override. Agents resolve and copy them with oat template resolve <name> --output <destination> rather than reading ~/.oat/templates/ directly.

For skills, compare frontmatter versions as a freshness check:

user version at or above the repository version is the expected state;
a higher repository version is an environment anomaly;
even in that anomaly, keep the user copy as the execution source, record the mismatch as a project-log learning, and refresh the user tier before safety-critical work.

Version comparison verifies provisioning. It never switches execution to the repository copy.

Cursor execution surfaces

Cursor Cloud native subagents, Cursor IDE subagents, the Cursor CLI subagent enum, and the Cursor CLI full model catalog are separate dispatch surfaces. Each can expose a differently named subset.

Snapshot the catalog for the surface being used before dispatch. Do not infer that a model available to a native cloud task is available to cursor-agent, or the reverse. The dispatch substrate owns route mechanics and records the selected surface, exact configured model string, selection reason, and accepted launch. See Programmatic Execution and Orchestration Model.

Autonomous runs

For an explicitly autonomous cloud run:

Resolve the primary repository and project home.
Verify the provisioned OAT and Cursor surfaces.
Invoke oat-project-autonomous; it activates the session-scoped autonomy signals.
Use the same policy boundaries and review contract as local autonomy.
Record cloud setup gaps, degraded checks, and freshness anomalies as category-bearing learnings in the project log (see learnings).

Missing credentials, repository-policy approval, destructive changes, unresolved blocking reviews, and material product ambiguity remain boundaries. See Autonomous Project Execution.

Learnings

The cloud skill records learnings with the same write as autonomous runs: oat project log append with --category (one of gotcha, efficiency, documentation-gap, candidate-skill-content, decision, environment-limited), a stable per-observation --source id that is also the --idempotency-key, and --origin oat-cursor-cloud-projects. A retried write appends nothing. When the project log is disabled and does not exist yet, the append creates nothing: the skill prints one warning line and continues, and the learning is not persisted. An existing project-log.md keeps accepting learnings. It never creates oat-execution-learnings.md. See Autonomous Project Execution for the category-to-type mapping and how summary reads the entries.

Autonomous Project Execution — activation, boundaries, review, and learnings.
Programmatic Execution — Cursor CLI and native execution surfaces.
Dispatch Policy — candidate ladders and exact route selection.
Configuration — user, shared, and repository-local config ownership.

oat-cursor-cloud-projects

Use this skill for cloud orientation before choosing a lifecycle action. It checks the environment, repository ownership, CLI, and assets. It does not run the project or activate autonomy on its own.

Invocation: In Cursor Cloud, the agent loads this skill on its own when a request involves OAT. You can also request orientation explicitly, or ask the agent how this cloud workspace should resolve OAT context. The slash form is an agent request, not a terminal command. Providers with $ syntax use $oat-cursor-cloud-projects.

/oat-cursor-cloud-projects
Identify the repository that owns this change and verify the OAT assets before continuing.

Prerequisites: Needs an active OAT project: no, but the skill uses one if it is set. A shell and Node/npm must be available. No active project is needed to detect cloud context or choose the target repository. When an active project exists, orientation resolves its scope and pulls synced context before reading artifacts. If the oat CLI cannot be installed, project artifact work stops.

What it does without asking: if oat is not on PATH, the skill runs npm install -g @open-agent-toolkit/cli@latest to install the latest CLI globally, and stops only if that install fails. If the active project is a synced project, it runs oat project pull to bring its artifacts into the checkout. When a repository skill is newer than the user-scope copy, or an expected skill, MCP server, CLI, or credential is missing, it records a learning in the active project's project-log.md. It activates autonomy only by loading oat-project-autonomous when you explicitly asked for an autonomous end-to-end run.

Example scenario: A cloud workspace contains both an application and a shared-library checkout. You want to resume application work without putting its project under the workspace parent. Orientation verifies cloud signals, selects the repository that owns the branch and eventual PR, resolves user-first skill assets, and then returns control to the correct lifecycle skill.

Expected output: An orientation summary reports detected context and its signal, target repository, projects root, active project or none, CLI readiness, asset tier, freshness, and any required dispatch context. Each skill and script resolves user, repository, then bundled scope. Templates use their separate repository-first CLI resolution. A higher repository skill version signals a stale user tier, not permission to switch sources silently.

Missing run metadata is disclosed. It does not justify inventing model identity. Without a cloud signal, the skill returns control without imposing cloud rules. Unavailable required capabilities and ambiguous repository ownership remain explicit boundaries.

Next step: Continue the owning project skill from the verified repository. For deliberately autonomous execution, invoke oat-project-autonomous separately. Orientation alone is not that authorization.

On this page