Tektona Docs

Create a new sandbox.

Authorization

apiKey

AuthorizationBearer <token>

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

In: header

Query Parameters

wait?boolean

Block until sandbox reaches running state (30s timeout).

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.

image*string

OCI image reference. Tag required. latest requires @sha256: digest.

location?string

Sandbox location. Defaults to the deployment's configured default location.

org*string

Organization slug.

project*string

Project slug.

public?boolean

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

resources?

Resource limits. Defaults: 2 CPU, 2 GiB memory, 10 GiB disk.

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://api-dev.tektona.ai/v1/sandboxes" \  -H "Content-Type: application/json" \  -d '{    "image": "ubuntu:24.04",    "org": "my-org",    "project": "my-project"  }'

{  "$schema": "https://api-dev.tektona.ai/schemas/CreateSandboxResponseBody.json",  "egress_network_policy": {    "name": "string"  },  "egress_proxy_profile": {    "name": "string"  },  "id": "01J5K3NDEKTSV4RRFFQ69G5FAV",  "image": "string",  "location": "string",  "org": "string",  "project": "string",  "public": true,  "resources": {    "cpu": 2,    "disk": 10,    "memory": 2  },  "state": "scheduling"}

{  "$schema": "https://api-dev.tektona.ai/schemas/ErrorModel.json",  "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"}

Create a sandbox