SandboxesManagement

Create a sandbox

Create a new sandbox.

  • The request waits up to 15 seconds for a node to be chosen. If placement is still pending, it returns 201 with the current state.
  • With wait=true, it then waits up to 30 more seconds for running or a terminal state. On timeout, it returns 201 with the current state.
  • It also returns when the node has downloaded the template image for 2 seconds.
  • This request does not stream progress. While the node downloads the image, GET /v1/sandboxes/{idOrName} returns image_pull.
POST
/v1/sandboxes
AuthorizationBearer <token>

API key starting with tektona_. Create one at app-dev.tektona.ai under API Keys.

In: header

Query Parameters

wait?boolean

After placement, also wait up to 30 more seconds for the sandbox to reach running or a terminal state. On timeout, the response has the current state.

Defaultfalse

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

auto_delete_after?string

Delete TTL after pause: a duration (e.g. '30d'), '0' for never, or omit to inherit.

auto_pause_after?string

Idle timeout before auto-pause: a duration (e.g. '15m'), '0' for never, or omit to inherit the project/platform default.

auto_pause_mode?string

Pause mode for auto-pause; omit to inherit.

Value in

  • "hibernate"
  • "suspend"
auto_resume?boolean

Wake the sandbox on incoming activity; omit to inherit.

egress_network_policy?string

Egress network policy reference: tektona/<name> (system), org/<name>, project/<name>, or a bare <name> (alias for project/<name>). Defaults to the project/org setting.

egress_proxy_profile?string

Egress proxy profile reference: org/<name>, project/<name>, or a bare <name> (alias for project/<name>). Defaults to the project default profile if set.

env?

Environment variables.

name?string

Sandbox name: lowercase letters, digits and hyphens, 1 to 40 characters, no hyphen at the start or the end. Unique among the live sandboxes of the project. It must not be a ULID (the sandbox ID format). Omit for no name.

Match^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
Lengthlength <= 40
org*string

Organization slug.

project*string

Project slug.

public?boolean

If true, sandbox is reachable via canonical preview URLs without a token.

region?string

Region to run the sandbox in. GET /v1/regions lists the regions. Defaults to the region of the installation.

Match^[a-z]{2}-[a-z]{3}-[1-9][0-9]*$
resources?

Resource limits. Defaults: 2 CPU, 2 GiB memory, 10 GiB disk, each reduced to the installation maximum when that is lower. Read the limits from GET /v1/sandbox-limits.

share_type?string

Share the sandbox with the project at creation. use lets project members operate it, and manage also lets them delete it. Default none: only the owner and project admins see it. The owner's credentials reach every member who can operate the sandbox.

Value in

  • "none"
  • "use"
  • "manage"
tags?array<string>|

Sandbox tags.

Itemsitems <= 20
template?string

Template reference: tektona/<name> (system), org/<name>, project/<name>, or a bare <name> (alias for project/<name>). An optional :<tag> selects a tag, and a version id in that position pins one build. No tag means :default.

user?string

The user the sandbox runs as, by name or uid, optionally with :group. Overrides the template version's spec.sandbox.user, which overrides the image's own USER. A name must exist in the image, or the sandbox fails to start. A uid needs no entry.

Match^[ -~]*$
Lengthlength <= 64
workdir?string

The absolute directory the sandbox starts in. Overrides the template version's spec.sandbox.workdir, which overrides the image's own WORKDIR. The sandbox creates it when it does not exist.

Match^/[ -~]*$
Lengthlength <= 255

Response Body

application/json

application/problem+json

curl -X POST "https://example.com/v1/sandboxes" \  -H "Content-Type: application/json" \  -d '{    "org": "my-org",    "project": "my-project"  }'
{  "access_endpoint": "https://fr-par-1.access.sandbox.tektona.app",  "egress_network_policy": {    "name": "string"  },  "egress_proxy_profile": {    "name": "string"  },  "id": "01J5K3NDEKTSV4RRFFQ69G5FAV",  "image": "string",  "name": "string",  "org": "string",  "project": "string",  "public": true,  "region": "fr-par-1",  "resources": {    "cpu": 2,    "disk": 10,    "memory": 2  },  "state": "scheduling",  "tags": [    "string"  ],  "template": {    "name": "go-dev",    "reference": "go-dev",    "scope": "system",    "tag": "stable",    "version_id": "01JABCDEF0123456789ABCDEFG"  }}