Cloud Runs (VS Code)

Cloud Runs lets VS Code extension users execute agent runs on the server — in a per-user dedicated pod — instead of locally on their machine. It's useful when a run is long or heavy and you want it off the user's laptop.

The feature ships off by default: nothing runs on the server until you explicitly enable it for the organization. This page is the administrator's side. For the end-user experience, see Cloud Runs in VS Code (usage).

One pod per user

When enabled, each authorized user gets a dedicated pod of the power class (1 vCPU / 2 GB). The pod is reused across that user's runs and reaped automatically once idle.

Where it's configured

Cloud Runs governance lives in /app, alongside the other organization rules, under the "VSCode Dev Studio" card. That's where you turn the feature on, choose who can use it, and set the limits.

The fundamental rule: fail-closed

A pod is created only when ALL of the conditions below pass together, in the same request:

1. The surface is VS Code (the extension).
2. The organization has Cloud Runs enabled.
3. The user has the cloud_run_user or cloud_run_admin role — and it is listed in allowed_roles.
4. The user confirmed (when required).
5. An admin approved (when required).
6. The workspace/repository is on the allowed list.
7. The concurrency quota hasn't been exceeded.

Any denial = no pod

Evaluation is fail-closed. If any of these conditions fails, nothing is provisioned on the server — the run is refused. The factory default is everything off: with no configuration at all, nobody runs on the server.

Governance fields

Under the "VSCode Dev Studio" card you control:

Field	Default	What it does
enabled (surface) + cloud_runs.enabled (sub-block)	OFF	Both must be ON for Cloud Runs to apply. The surface turns on VSCode Dev Studio; the sub-block turns on Cloud Runs specifically.
allowed_roles	empty	Which roles may use it: cloud_run_user, cloud_run_admin. Empty = nobody (fail-closed).
require_confirmation	true	The extension requires a confirmation modal before starting a run on the server.
require_admin_approval	false	Requires an admin's approval before the run executes.
warm.idle_ttl_minutes	30 (range 5–240)	How long the pod stays warm and idle before being reaped.
resources	power class (1 vCPU / 2 GB)	The pod's resource class. Read-only — it's the only class available at this stage.
limits.max_duration_minutes	60 (range 5–480)	A hard ceiling on a run's duration (see the warning below).
limits.max_parallel_runs_per_user	1	How many simultaneous runs a single user can have.
limits.max_parallel_runs_per_org	5	How many simultaneous runs the whole organization can have.
workspaces / repositories	—	Allow/deny lists of workspaces and repositories. Deny wins.

max_duration_minutes is a ceiling that terminates the run

It isn't just a target: past the maximum (plus a short grace period), the run is terminated even mid-flight. Size it with margin so legitimate work isn't cut off — and use it as a cost ceiling.

Roles

Assign one of the two roles to authorized users, in Users & roles:

Role	Allows
cloud_run_user	Using Cloud Runs (starting runs on the server).
cloud_run_admin	Using and editing this governance (the "VSCode Dev Studio" card).

The role alone isn't enough: it must also be in allowed_roles. A user without the role (or outside allowed_roles) is denied with role_required.

Pod lifecycle

The pod isn't created and destroyed per run — it is reused by the same user across runs. It is reaped automatically when:

• it stays idle beyond warm.idle_ttl_minutes;
• the run exceeds limits.max_duration_minutes;
• you turn the governance off — disabling Cloud Runs for the organization removes that org's pods.

Turning it off is immediate and cleans everything

Setting cloud_runs.enabled (or the surface) to OFF doesn't just block new runs: it removes that organization's existing pods. Use it if you need to cut off the server quickly.

Observability (platform team)

There is a read-only view of Cloud Run pods in the internal /staff console, for platform diagnostics — it is not tenant governance. Whoever administers the organization does everything in /app, under the "VSCode Dev Studio" card. /staff exists so the platform team can observe pod state, not to configure an organization's policy.

Good practices

Start conservative

• Keep require_confirmation=true — the user always confirms before spending server resources.
• Grant cloud_run_user/cloud_run_admin only to those who truly need it.
• Use max_duration_minutes and the concurrency limits (max_parallel_runs_per_user / per_org) as a cost ceiling.
• Remember: an empty allowed_roles blocks everyone — that's the expected fail-closed behavior.

See also

☁️Cloud Runs in VS Code (usage)

The experience of those starting runs on the server.

Open →👥Users & roles

Where you assign cloud_run_user and cloud_run_admin.

Open →🛡️Governance & policies

The organization's rules and how they combine.

Open →