NylorunDocsBeta
Runtime APISandboxes

Create or find a sandbox

PUT
/v1/sandboxes/{sandboxId}

Creates the sandbox within the Tenant's limits, or answers the one with this id, so get-or-create is one call. Its spec is fixed once it exists; labels, when sent, replace its labels. Kind pod needs sandbox pods (nylorun sandbox enable): it is created at once, and a PUT on an existing pod sandbox starts it again when it was stopped, or revives it with a longer lifecycle.ttl.

Authorization

headerAuthorizationBearer <token>

An application key of the Tenant (PUT /v1/tenant/keys/{keyId}), or Studio's key, derived from the admin key. With Nylorun-Subject and Nylorun-Scopes, it acts for that person, narrowed to those scopes. Never accepted from a browser (Origin).

Path Parameters

sandboxId*string

The sandbox id, percent-encoded: team-a%2Fproj-42 for team-a/proj-42

Header Parameters

Nylorun-Protocol*string

The protocol version, 8

Nylorun-Subject?string

The person an application key acts for

Nylorun-Scopes?string

The subject's space-separated scopes; required with a subject

Request Body

application/json
  1. body
requestId?string
Length1 <= length
kind?string
Value in"virtual""pod"
labels?
image?string
Length1 <= length
network?
resources?
storage?string
lifecycle?

Response Body

The sandbox

application/json
  1. response
id*string
kind*string
Value in"virtual""pod"
labels*
spec*
state*string
Value in"ready""creating""running""stopped"
pod?
sessions*array<>
createdAt*string
updatedAt*string
import { createClient } from "@nylorun/agents";const client = await createClient();const sandbox = await client.sandboxes.ensure("build-box", {  labels: { team: "ops" },});
{  "id": "string",  "kind": "virtual",  "labels": {    "property1": "string",    "property2": "string"  },  "spec": {    "property1": null,    "property2": null  },  "state": "ready",  "pod": {    "desired": "running",    "observed": "creating",    "volumeGeneration": 0,    "hostEpoch": 0,    "expiresAt": "string",    "reason": "string"  },  "sessions": [    {      "id": "string",      "activeTurnId": "string"    }  ],  "createdAt": "string",  "updatedAt": "string"}

Call an agent over A2A POST

A2A 1.0 JSON-RPC, for a subject: `SendMessage` (blocking up to 5 minutes, or `returnImmediately`), `GetTask` and `CancelTask`. A context is one session per subject, agent and `contextId`; a task is one turn. JSON-RPC errors are answered with 200; limits, scopes and unavailable streams stay HTTP errors.

Get a sandbox GET

Its spec, labels, state and the sessions attached to it (acting for a person, only theirs).