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 forrunningor 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}returnsimage_pull.
Authorization
apiKey API key starting with tektona_. Create one at app-dev.tektona.ai under API Keys.
In: header
Query Parameters
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.
falseRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Delete TTL after pause: a duration (e.g. '30d'), '0' for never, or omit to inherit.
Idle timeout before auto-pause: a duration (e.g. '15m'), '0' for never, or omit to inherit the project/platform default.
Pause mode for auto-pause; omit to inherit.
Value in
- "hibernate"
- "suspend"
Wake the sandbox on incoming activity; omit to inherit.
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 reference: org/<name>, project/<name>, or a bare <name> (alias for project/<name>). Defaults to the project default profile if set.
Environment variables.
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.
^[a-z0-9]([a-z0-9-]*[a-z0-9])?$length <= 40Organization slug.
Project slug.
If true, sandbox is reachable via canonical preview URLs without a token.
Region to run the sandbox in. GET /v1/regions lists the regions. Defaults to the region of the installation.
^[a-z]{2}-[a-z]{3}-[1-9][0-9]*$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 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"
Sandbox tags.
items <= 20Template 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.
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.
^[ -~]*$length <= 64The 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.
^/[ -~]*$length <= 255Response 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" }}{ "detail": "Property foo is required but is missing.", "errors": [ { "location": "string", "message": "string", "value": null } ], "instance": "https://example.com/error-log/abc123", "status": 400, "title": "Bad Request", "type": "https://example.com/errors/example"}