Sandbox

View as Markdown

A Sandbox resource representing an execution environment.

Get a sandboxGET /api/2.0/{name=sandboxes/*}List sandboxesGET /api/2.0/sandboxesCreate a sandboxPOST /api/2.0/sandboxesUpdate a sandboxPATCH /api/2.0/{name=sandboxes/*}Delete a sandboxDELETE /api/2.0/{name=sandboxes/*}Start a sandboxPOST /api/2.0/{name=sandboxes/*}/startStop a sandboxPOST /api/2.0/{name=sandboxes/*}/stopRun a command in a sandbox and wait for its resultPOST /api/2.0/sandbox-exec/{name=sandboxes/*}/exec-syncList the tracked command executions in a sandboxGET /api/2.0/sandbox-exec/{parent=sandboxes/*}/commands

Sandbox object

A Sandbox resource representing an execution environment.

specobjectBeta

The desired configuration of the sandbox, supplied by the caller at creation time.

Show child attributesHide child attributes

computeobjectBeta

Compute configuration (size, inactivity timeout) requested for the sandbox.

Show child attributesHide child attributes

inactivity_timeoutstringBeta

Idle duration after which the sandbox is automatically terminated.

statusobjectBetaOutput only

The observed runtime state of the sandbox, populated by the server.

Show child attributesHide child attributes

statestringBetaOutput only

Lifecycle state of the sandbox.

Values:

• SANDBOX_STATE_UNSPECIFIED
• SANDBOX_STATE_PENDING
• SANDBOX_STATE_RUNNING
• SANDBOX_STATE_STOPPED
• SANDBOX_STATE_STOPPING

namestringBetaIDImmutable

The sandbox resource name, in the form sandboxes/{sandbox_id}. Derived from sandbox_id; any value supplied in a create or update request body is ignored.

create_timestringBetaOutput only

Output only. The creation time of the sandbox.

update_timestringBetaOutput only

Output only. The last update time of the sandbox metadata and spec.

display_namestringBeta

Human-readable display label for the sandbox. At most 256 characters.

View as Markdown

The Sandbox object

{
  "spec": {
    "compute": {}
  },
  "status": {
    "state": "SANDBOX_STATE_PENDING"
  },
  "name": "string",
  "create_time": "string",
  "update_time": "string",
  "display_name": "string"
}

Get a sandbox Beta

GET /api/2.0/{name=sandboxes/*}

Retrieves a Sandbox by name.

API scopes: sandbox

Parameters

namestringRequiredpath

Response

Returns the Sandbox object.

View as Markdown

Response

{
  "spec": {
    "compute": {}
  },
  "status": {
    "state": "SANDBOX_STATE_PENDING"
  },
  "name": "string",
  "create_time": "string",
  "update_time": "string",
  "display_name": "string"
}

List sandboxes Beta

GET /api/2.0/sandboxes

Lists all Sandboxes.

API scopes: sandbox

Parameters

page_tokenstringquery

page_sizeint32query

Response

Returns a list of Sandbox objects.

View as Markdown

Response

{
  "sandboxes": [
    {
      "spec": {},
      "status": {},
      "name": "string",
      "create_time": "string",
      "update_time": "string",
      "display_name": "string"
    }
  ],
  "next_page_token": "string"
}

Create a sandbox Beta

POST /api/2.0/sandboxes

Creates a new Sandbox.

API scopes: sandbox

Parameters

sandbox_idstringRequiredquery

Client-supplied ID that becomes the final path segment of the resource name.

Request body

The sandbox to create.

specobject

The desired configuration of the sandbox, supplied by the caller at creation time.

Show child attributesHide child attributes

computeobject

Compute configuration (size, inactivity timeout) requested for the sandbox.

Show child attributesHide child attributes

inactivity_timeoutstring

Idle duration after which the sandbox is automatically terminated.

namestringIDImmutable

The sandbox resource name, in the form sandboxes/{sandbox_id}. Derived from sandbox_id; any value supplied in a create or update request body is ignored.

display_namestring

Human-readable display label for the sandbox. At most 256 characters.

Response

Returns the Sandbox object.

View as Markdown

Request

{
  "spec": {
    "compute": {}
  },
  "name": "string",
  "display_name": "string"
}

Response

{
  "spec": {
    "compute": {}
  },
  "status": {
    "state": "SANDBOX_STATE_PENDING"
  },
  "name": "string",
  "create_time": "string",
  "update_time": "string",
  "display_name": "string"
}

Update a sandbox Beta

PATCH /api/2.0/{name=sandboxes/*}

Updates mutable fields on an existing Sandbox. Allowlisted update_mask paths today: display_name, spec.compute.inactivity_timeout. Returns INVALID_PARAMETER_VALUE for empty masks or unknown paths; NOT_FOUND if the sandbox does not exist.

API scopes: sandbox

Parameters

namestringRequiredpath

Resource name of the sandbox to update, in the form sandboxes/{sandbox_id}.

update_maskstringRequiredquery

Field paths to update. Must be a non-empty subset of:

• display_name
• spec.compute.inactivity_timeout Any other path returns INVALID_PARAMETER_VALUE.

Request body

The Sandbox resource carrying new field values. Only fields named in update_mask are read; unmasked fields are ignored.

specobject

The desired configuration of the sandbox, supplied by the caller at creation time.

Show child attributesHide child attributes

computeobject

Compute configuration (size, inactivity timeout) requested for the sandbox.

Show child attributesHide child attributes

inactivity_timeoutstring

Idle duration after which the sandbox is automatically terminated.

namestringIDImmutable

The sandbox resource name, in the form sandboxes/{sandbox_id}. Derived from sandbox_id; any value supplied in a create or update request body is ignored.

display_namestring

Human-readable display label for the sandbox. At most 256 characters.

Response

Returns the Sandbox object.

View as Markdown

Request

{
  "spec": {
    "compute": {}
  },
  "name": "string",
  "display_name": "string"
}

Response

{
  "spec": {
    "compute": {}
  },
  "status": {
    "state": "SANDBOX_STATE_PENDING"
  },
  "name": "string",
  "create_time": "string",
  "update_time": "string",
  "display_name": "string"
}

Delete a sandbox Beta

DELETE /api/2.0/{name=sandboxes/*}

Deletes a Sandbox.

API scopes: sandbox

Parameters

namestringRequiredpath

View as Markdown

Response

{}

Start a sandbox Beta

POST /api/2.0/{name=sandboxes/*}/start

Starts a previously stopped Sandbox under the same sandbox name. Returns NOT_FOUND if there is no stopped sandbox to start for the given name.

API scopes: sandbox

Parameters

namestringRequiredpath

Resource name of the sandbox to start, in the form sandboxes/{sandbox_id}.

Response

Returns the Sandbox object.

View as Markdown

Response

{
  "spec": {
    "compute": {}
  },
  "status": {
    "state": "SANDBOX_STATE_PENDING"
  },
  "name": "string",
  "create_time": "string",
  "update_time": "string",
  "display_name": "string"
}

Stop a sandbox Beta

POST /api/2.0/{name=sandboxes/*}/stop

Stops a running Sandbox, preserving it so it can later be restarted with a Start request.

API scopes: sandbox

Parameters

namestringRequiredpath

Resource name of the sandbox to stop, in the form sandboxes/{sandbox_id}.

Response

Returns the Sandbox object.

View as Markdown

Response

{
  "spec": {
    "compute": {}
  },
  "status": {
    "state": "SANDBOX_STATE_PENDING"
  },
  "name": "string",
  "create_time": "string",
  "update_time": "string",
  "display_name": "string"
}

Run a command in a sandbox and wait for its result Beta

POST /api/2.0/sandbox-exec/{name=sandboxes/*}/exec-sync

Runs a command in the sandbox and blocks until it exits, returning the captured stdout, stderr and exit code in a single response.

API scopes: sandbox

Parameters

namestringRequiredpath

Resource name of the sandbox to run the command in, in the form sandboxes/{sandbox_id}. Bound from the URL path.

Request body

cmdstringRequired

Executable or command to run (e.g. /bin/echo, python3).

argsarray of string

Arguments passed to cmd.

envsobject

Extra environment variables for the command's process, merged over the sandbox's default environment.

execution_timeoutstring

Maximum time to wait for the command to finish. When it elapses the command is terminated and the response carries status TIMED_OUT. The server applies a default when unset and clamps to an upper bound; negative or otherwise invalid durations are rejected with INVALID_ARGUMENT.

Response

exit_codeint32Output only

Process exit code. Unset when the process was terminated by a signal (e.g. on TIMED_OUT) or never started (FAILED) rather than exiting normally.

statusstringOutput only

Terminal status of the command execution. Always set on a successful response; never EXECUTE_COMMAND_STATUS_UNSPECIFIED.

Values:

• EXECUTE_COMMAND_STATUS_UNSPECIFIED
• EXECUTE_COMMAND_STATUS_COMPLETED
• EXECUTE_COMMAND_STATUS_TIMED_OUT
• EXECUTE_COMMAND_STATUS_FAILED

stdoutstringOutput only

Captured standard output as UTF-8 text. Invalid UTF-8 bytes are replaced with the Unicode replacement character (U+FFFD).

stderrstringOutput only

Captured standard error, with the same UTF-8 semantics as stdout.

command_idstringOutput only

Daemon-generated identifier for this command execution, for correlation (for example in ListCommands).

truncatedbooleanOutput only

True when stdout / stderr were truncated because the captured output exceeded the server's per-response size cap. The dropped output is not included in this response and is not recoverable through this unary API.

View as Markdown

Request

{
  "cmd": "string",
  "args": [
    "string"
  ],
  "envs": {},
  "execution_timeout": "string"
}

Response

{
  "exit_code": 0,
  "status": "EXECUTE_COMMAND_STATUS_COMPLETED",
  "stdout": "string",
  "stderr": "string",
  "command_id": "string",
  "truncated": true
}

List the tracked command executions in a sandbox Beta

GET /api/2.0/sandbox-exec/{parent=sandboxes/*}/commands

Lists the tracked command executions (running and completed) in a sandbox.

API scopes: sandbox

Parameters

parentstringRequiredpath

The sandbox whose commands to list, in the form sandboxes/{sandbox_id}.

page_sizeint32query

Maximum number of commands to return. The server may return fewer. If unspecified, the server returns all commands.

page_tokenstringquery

Page token returned by a previous ListCommands call. Use this to retrieve the next page of results.

Response

commandsarray of object

Commands in this page of results.

Show child attributesHide child attributes

command_idstring

Stable identifier for this command.

cmdstring

The program that was executed.

argsarray of string

Arguments passed to the program.

pidint64

PID of the spawned process. Absent if the process failed to start.

finishedboolean

Whether the command has finished executing.

exit_codeint32

Process exit code. Only present when finished is true and the process exited normally (not killed by signal or failed to start).

next_page_tokenstring

Token to retrieve the next page. Empty when there are no more results.

View as Markdown

Response

{
  "commands": [
    {
      "command_id": "string",
      "cmd": "string",
      "args": [
        "string"
      ],
      "pid": 0,
      "finished": true,
      "exit_code": 0
    }
  ],
  "next_page_token": "string"
}