Create environment
Defines the sandbox an agent session runs in and returns the stored environment, including its generated environment_id. The provider must be one this deployment reports from managedAgentsListSandboxProviders. Privileged Docker requires unrestricted internet access (networkPolicy: ). Nothing is provisioned by this configuration write; compute is allocated when managedAgentsCreateEnvironmentSetupRun or a session references the environment. An environment with a setup script must be verified (managedAgentsCreateEnvironmentSetupRun) before a session on the runs or docker provider will start. Send Idempotency-Key to make a retry after an ambiguous transport failure replay the original response instead of creating another environment.
Authorizations
Headers
Replay-protection key in an organization-wide namespace shared by keyed mutations. It must contain 1 to 256 visible ASCII characters and be sent as exactly one header value. Request identity is the exact HTTP method, escaped path, raw query, and raw body bytes. The same request replays the original successful response; any different request returns 409 idempotency_conflict, and an active matching request returns 409 idempotency_in_progress. Completed receipts are retained for approximately 24 hours, pending claims may be reclaimed after approximately 1 hour, and no deduplication is guaranteed after expiry.
1 - 256^[!-~]+$Body
Request body for creating a standalone environment.
Internet access for Runs environments. Omit for No access; send {} for unrestricted access. A nonempty policy limits destinations and cannot be combined with privileged Docker. If the selected placement is incompatible, choose a compatible placement or send {} for unrestricted access.
Seconds after a sandbox stops before it may be released, from 3600 (an hour) to 2592000 (30 days). This does not expire the session. Send another message to resume it; /workspace files can be used when its workspace reopens. Omit or send 0 to use the service default.
0 <= x <= 9007199254740991Response
A standalone sandbox environment a session executes in.
A standalone sandbox environment a session executes in.
Plaintext environment variables exported in the sandbox. They become the whole container environment, including the runner entrypoint's, so PATH is refused (env_vars.PATH): managed images select /workspace/.venv themselves. A Runs session using one-time setup after its runner changes also refuses startup-hook names such as BASH_ENV, HOME, PYTHONPATH, and LD_PRELOAD; re-test to capture a compatible image instead. Never put secrets here; store them as vault credentials instead. On update, omit to keep the current variables; send {} to clear them.
Seconds of inactivity after which a running sandbox is stopped, from 120 to 7200 (2 hours); 0 uses the provider default. A computer-enabled environment requires 0 or at least 600 seconds so its five-minute handoff heartbeat arrives before idle-stop.
0 <= x <= 9007199254740991Whether a Runs sandbox may use privileged Docker. Privileged Docker requires unrestricted internet access (networkPolicy: {}) on create or when changing access settings. Omit on update to keep the current value, or send false to disable it. New Runs environments and transitions from another provider default to false. Existing environments with both limited internet access and privileged Docker remain visible and allow edits to other settings. To start a new session, set networkPolicy: {} or disable privileged Docker.
Deprecated and always empty for new environments. Environment secret references are no longer supported; use vault credentials instead. An environment stored with references cannot start sessions or setup runs until an update sends {} to clear them; clearing them marks the setup verdict stale, so re-test afterwards.
Advisory findings about the setup script (bash -lc wrapping, curl | sh, unpinned installs, ambiguous system Python, PATH replacement, or non-persistent shell activation), plus legacy_setup_discarded when the stored setup predates setup.script and is not run. Never block a save; computed on read.
Seconds after a sandbox stops before it may be released, from 3600 (an hour) to 2592000 (30 days); 0 uses the service default. This does not expire the session. Send another message to resume it; /workspace files can be used when its workspace reopens.
0 <= x <= 9007199254740991