Post v1sandboxes

cURL

curl --request POST \
  --url https://api.example.com/v1/sandboxes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'idempotency-key: <idempotency-key>' \
  --data '
{
  "image": "<string>",
  "ttl_seconds": 2,
  "storage_class": "standard",
  "ports": [
    32768
  ],
  "volumes": [
    {
      "volume_id": "<string>",
      "target_path": "<string>"
    }
  ],
  "secrets": [
    {
      "name": "<string>"
    }
  ],
  "metadata": {},
  "name": "<string>",
  "resources": {
    "memory_mb": 524288,
    "gpus": {
      "count": 123,
      "models": [
        "<string>"
      ]
    },
    "cpu_millis": 64025
  },
  "command": [
    "<string>"
  ],
  "workspace_capacity_gib": 2,
  "idle_timeout_seconds": 43230,
  "shared_filesystems": [
    {
      "filesystem_id": "<string>",
      "subdirectory": "<string>",
      "target_path": "<string>"
    }
  ]
}
'

import requests

url = "https://api.example.com/v1/sandboxes"

payload = {
    "image": "<string>",
    "ttl_seconds": 2,
    "storage_class": "standard",
    "ports": [32768],
    "volumes": [
        {
            "volume_id": "<string>",
            "target_path": "<string>"
        }
    ],
    "secrets": [{ "name": "<string>" }],
    "metadata": {},
    "name": "<string>",
    "resources": {
        "memory_mb": 524288,
        "gpus": {
            "count": 123,
            "models": ["<string>"]
        },
        "cpu_millis": 64025
    },
    "command": ["<string>"],
    "workspace_capacity_gib": 2,
    "idle_timeout_seconds": 43230,
    "shared_filesystems": [
        {
            "filesystem_id": "<string>",
            "subdirectory": "<string>",
            "target_path": "<string>"
        }
    ]
}
headers = {
    "idempotency-key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'idempotency-key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    image: '<string>',
    ttl_seconds: 2,
    storage_class: 'standard',
    ports: [32768],
    volumes: [{volume_id: '<string>', target_path: '<string>'}],
    secrets: [{name: '<string>'}],
    metadata: {},
    name: '<string>',
    resources: {memory_mb: 524288, gpus: {count: 123, models: ['<string>']}, cpu_millis: 64025},
    command: ['<string>'],
    workspace_capacity_gib: 2,
    idle_timeout_seconds: 43230,
    shared_filesystems: [{filesystem_id: '<string>', subdirectory: '<string>', target_path: '<string>'}]
  })
};

fetch('https://api.example.com/v1/sandboxes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/sandboxes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'image' => '<string>',
    'ttl_seconds' => 2,
    'storage_class' => 'standard',
    'ports' => [
        32768
    ],
    'volumes' => [
        [
                'volume_id' => '<string>',
                'target_path' => '<string>'
        ]
    ],
    'secrets' => [
        [
                'name' => '<string>'
        ]
    ],
    'metadata' => [
        
    ],
    'name' => '<string>',
    'resources' => [
        'memory_mb' => 524288,
        'gpus' => [
                'count' => 123,
                'models' => [
                                '<string>'
                ]
        ],
        'cpu_millis' => 64025
    ],
    'command' => [
        '<string>'
    ],
    'workspace_capacity_gib' => 2,
    'idle_timeout_seconds' => 43230,
    'shared_filesystems' => [
        [
                'filesystem_id' => '<string>',
                'subdirectory' => '<string>',
                'target_path' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "idempotency-key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/sandboxes"

	payload := strings.NewReader("{\n  \"image\": \"<string>\",\n  \"ttl_seconds\": 2,\n  \"storage_class\": \"standard\",\n  \"ports\": [\n    32768\n  ],\n  \"volumes\": [\n    {\n      \"volume_id\": \"<string>\",\n      \"target_path\": \"<string>\"\n    }\n  ],\n  \"secrets\": [\n    {\n      \"name\": \"<string>\"\n    }\n  ],\n  \"metadata\": {},\n  \"name\": \"<string>\",\n  \"resources\": {\n    \"memory_mb\": 524288,\n    \"gpus\": {\n      \"count\": 123,\n      \"models\": [\n        \"<string>\"\n      ]\n    },\n    \"cpu_millis\": 64025\n  },\n  \"command\": [\n    \"<string>\"\n  ],\n  \"workspace_capacity_gib\": 2,\n  \"idle_timeout_seconds\": 43230,\n  \"shared_filesystems\": [\n    {\n      \"filesystem_id\": \"<string>\",\n      \"subdirectory\": \"<string>\",\n      \"target_path\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("idempotency-key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/sandboxes")
  .header("idempotency-key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"image\": \"<string>\",\n  \"ttl_seconds\": 2,\n  \"storage_class\": \"standard\",\n  \"ports\": [\n    32768\n  ],\n  \"volumes\": [\n    {\n      \"volume_id\": \"<string>\",\n      \"target_path\": \"<string>\"\n    }\n  ],\n  \"secrets\": [\n    {\n      \"name\": \"<string>\"\n    }\n  ],\n  \"metadata\": {},\n  \"name\": \"<string>\",\n  \"resources\": {\n    \"memory_mb\": 524288,\n    \"gpus\": {\n      \"count\": 123,\n      \"models\": [\n        \"<string>\"\n      ]\n    },\n    \"cpu_millis\": 64025\n  },\n  \"command\": [\n    \"<string>\"\n  ],\n  \"workspace_capacity_gib\": 2,\n  \"idle_timeout_seconds\": 43230,\n  \"shared_filesystems\": [\n    {\n      \"filesystem_id\": \"<string>\",\n      \"subdirectory\": \"<string>\",\n      \"target_path\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/sandboxes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["idempotency-key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"image\": \"<string>\",\n  \"ttl_seconds\": 2,\n  \"storage_class\": \"standard\",\n  \"ports\": [\n    32768\n  ],\n  \"volumes\": [\n    {\n      \"volume_id\": \"<string>\",\n      \"target_path\": \"<string>\"\n    }\n  ],\n  \"secrets\": [\n    {\n      \"name\": \"<string>\"\n    }\n  ],\n  \"metadata\": {},\n  \"name\": \"<string>\",\n  \"resources\": {\n    \"memory_mb\": 524288,\n    \"gpus\": {\n      \"count\": 123,\n      \"models\": [\n        \"<string>\"\n      ]\n    },\n    \"cpu_millis\": 64025\n  },\n  \"command\": [\n    \"<string>\"\n  ],\n  \"workspace_capacity_gib\": 2,\n  \"idle_timeout_seconds\": 43230,\n  \"shared_filesystems\": [\n    {\n      \"filesystem_id\": \"<string>\",\n      \"subdirectory\": \"<string>\",\n      \"target_path\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "request_state": "requested",
  "run_id": "<string>"
}

{
  "code": "<string>",
  "message": "<string>",
  "request_id": "<string>",
  "metric": "<string>",
  "limit": 123,
  "retry_after_seconds": 123
}

{
  "code": "<string>",
  "message": "<string>",
  "request_id": "<string>"
}

POST

sandboxes

cURL

curl --request POST \
  --url https://api.example.com/v1/sandboxes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'idempotency-key: <idempotency-key>' \
  --data '
{
  "image": "<string>",
  "ttl_seconds": 2,
  "storage_class": "standard",
  "ports": [
    32768
  ],
  "volumes": [
    {
      "volume_id": "<string>",
      "target_path": "<string>"
    }
  ],
  "secrets": [
    {
      "name": "<string>"
    }
  ],
  "metadata": {},
  "name": "<string>",
  "resources": {
    "memory_mb": 524288,
    "gpus": {
      "count": 123,
      "models": [
        "<string>"
      ]
    },
    "cpu_millis": 64025
  },
  "command": [
    "<string>"
  ],
  "workspace_capacity_gib": 2,
  "idle_timeout_seconds": 43230,
  "shared_filesystems": [
    {
      "filesystem_id": "<string>",
      "subdirectory": "<string>",
      "target_path": "<string>"
    }
  ]
}
'

import requests

url = "https://api.example.com/v1/sandboxes"

payload = {
    "image": "<string>",
    "ttl_seconds": 2,
    "storage_class": "standard",
    "ports": [32768],
    "volumes": [
        {
            "volume_id": "<string>",
            "target_path": "<string>"
        }
    ],
    "secrets": [{ "name": "<string>" }],
    "metadata": {},
    "name": "<string>",
    "resources": {
        "memory_mb": 524288,
        "gpus": {
            "count": 123,
            "models": ["<string>"]
        },
        "cpu_millis": 64025
    },
    "command": ["<string>"],
    "workspace_capacity_gib": 2,
    "idle_timeout_seconds": 43230,
    "shared_filesystems": [
        {
            "filesystem_id": "<string>",
            "subdirectory": "<string>",
            "target_path": "<string>"
        }
    ]
}
headers = {
    "idempotency-key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'idempotency-key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    image: '<string>',
    ttl_seconds: 2,
    storage_class: 'standard',
    ports: [32768],
    volumes: [{volume_id: '<string>', target_path: '<string>'}],
    secrets: [{name: '<string>'}],
    metadata: {},
    name: '<string>',
    resources: {memory_mb: 524288, gpus: {count: 123, models: ['<string>']}, cpu_millis: 64025},
    command: ['<string>'],
    workspace_capacity_gib: 2,
    idle_timeout_seconds: 43230,
    shared_filesystems: [{filesystem_id: '<string>', subdirectory: '<string>', target_path: '<string>'}]
  })
};

fetch('https://api.example.com/v1/sandboxes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/sandboxes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'image' => '<string>',
    'ttl_seconds' => 2,
    'storage_class' => 'standard',
    'ports' => [
        32768
    ],
    'volumes' => [
        [
                'volume_id' => '<string>',
                'target_path' => '<string>'
        ]
    ],
    'secrets' => [
        [
                'name' => '<string>'
        ]
    ],
    'metadata' => [
        
    ],
    'name' => '<string>',
    'resources' => [
        'memory_mb' => 524288,
        'gpus' => [
                'count' => 123,
                'models' => [
                                '<string>'
                ]
        ],
        'cpu_millis' => 64025
    ],
    'command' => [
        '<string>'
    ],
    'workspace_capacity_gib' => 2,
    'idle_timeout_seconds' => 43230,
    'shared_filesystems' => [
        [
                'filesystem_id' => '<string>',
                'subdirectory' => '<string>',
                'target_path' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "idempotency-key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/sandboxes"

	payload := strings.NewReader("{\n  \"image\": \"<string>\",\n  \"ttl_seconds\": 2,\n  \"storage_class\": \"standard\",\n  \"ports\": [\n    32768\n  ],\n  \"volumes\": [\n    {\n      \"volume_id\": \"<string>\",\n      \"target_path\": \"<string>\"\n    }\n  ],\n  \"secrets\": [\n    {\n      \"name\": \"<string>\"\n    }\n  ],\n  \"metadata\": {},\n  \"name\": \"<string>\",\n  \"resources\": {\n    \"memory_mb\": 524288,\n    \"gpus\": {\n      \"count\": 123,\n      \"models\": [\n        \"<string>\"\n      ]\n    },\n    \"cpu_millis\": 64025\n  },\n  \"command\": [\n    \"<string>\"\n  ],\n  \"workspace_capacity_gib\": 2,\n  \"idle_timeout_seconds\": 43230,\n  \"shared_filesystems\": [\n    {\n      \"filesystem_id\": \"<string>\",\n      \"subdirectory\": \"<string>\",\n      \"target_path\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("idempotency-key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/sandboxes")
  .header("idempotency-key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"image\": \"<string>\",\n  \"ttl_seconds\": 2,\n  \"storage_class\": \"standard\",\n  \"ports\": [\n    32768\n  ],\n  \"volumes\": [\n    {\n      \"volume_id\": \"<string>\",\n      \"target_path\": \"<string>\"\n    }\n  ],\n  \"secrets\": [\n    {\n      \"name\": \"<string>\"\n    }\n  ],\n  \"metadata\": {},\n  \"name\": \"<string>\",\n  \"resources\": {\n    \"memory_mb\": 524288,\n    \"gpus\": {\n      \"count\": 123,\n      \"models\": [\n        \"<string>\"\n      ]\n    },\n    \"cpu_millis\": 64025\n  },\n  \"command\": [\n    \"<string>\"\n  ],\n  \"workspace_capacity_gib\": 2,\n  \"idle_timeout_seconds\": 43230,\n  \"shared_filesystems\": [\n    {\n      \"filesystem_id\": \"<string>\",\n      \"subdirectory\": \"<string>\",\n      \"target_path\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/sandboxes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["idempotency-key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"image\": \"<string>\",\n  \"ttl_seconds\": 2,\n  \"storage_class\": \"standard\",\n  \"ports\": [\n    32768\n  ],\n  \"volumes\": [\n    {\n      \"volume_id\": \"<string>\",\n      \"target_path\": \"<string>\"\n    }\n  ],\n  \"secrets\": [\n    {\n      \"name\": \"<string>\"\n    }\n  ],\n  \"metadata\": {},\n  \"name\": \"<string>\",\n  \"resources\": {\n    \"memory_mb\": 524288,\n    \"gpus\": {\n      \"count\": 123,\n      \"models\": [\n        \"<string>\"\n      ]\n    },\n    \"cpu_millis\": 64025\n  },\n  \"command\": [\n    \"<string>\"\n  ],\n  \"workspace_capacity_gib\": 2,\n  \"idle_timeout_seconds\": 43230,\n  \"shared_filesystems\": [\n    {\n      \"filesystem_id\": \"<string>\",\n      \"subdirectory\": \"<string>\",\n      \"target_path\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "request_state": "requested",
  "run_id": "<string>"
}

{
  "code": "<string>",
  "message": "<string>",
  "request_id": "<string>",
  "metric": "<string>",
  "limit": 123,
  "retry_after_seconds": 123
}

{
  "code": "<string>",
  "message": "<string>",
  "request_id": "<string>"
}

Authorizations

Authorization

string

header

required

Hiloop API key sent as an HTTP Bearer token.

Headers

idempotency-key

string

required

Required idempotency key for this mutation. The server records the result from execution start. For at least 72 hours, reuse by the same organization and route replays the original status and body. A matching request still in flight or reuse for different input returns 409 idempotency_conflict. Keys are scoped by organization and route and contain 1-255 characters.

Required string length: 1 - 255

Body

application/json

Option 1
Option 2

Create a root sandbox from an OCI image; omitting image starts from the platform default image.

image

string

The unmodified OCI image reference to start from.

Minimum string length: 1

ttl_seconds

integer<uint32>

Sandbox lifetime in seconds. Omit it to use the deployment default.

Required range: x >= 1

storage_class

enum<string>

default:standard

Storage behavior for the sandbox. Omit it to use durable storage when restoring a snapshot, or standard storage for an image/platform-default create.

Available options:

standard,

durable

ports

integer<uint32>[]

Unique guest TCP ports in the range 1-65535. Returned endpoints are authenticated private session-plane connections, not public preview URLs.

Required range: 1 <= x <= 65535

volumes

object[]

Pre-registered volumes to mount, each pinned to its current version at admission.

Show child attributes

secrets

object[]

Pre-registered secrets to bind for proof-bound request-time delivery.

Show child attributes

metadata

object

Caller-owned metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content.

Show child attributes

name

string

Optional customer-supplied name, unique among the project's sandboxes that have not finished deleting. It must be 1-63 characters: lowercase letters or digits, with interior hyphens allowed. Omit it to leave the sandbox unnamed; the server never generates a name. A duplicate returns 409 name_conflict; a terminated sandbox's name is free to reuse, and its record keeps the name for history.

Required string length: 1 - 63

Pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$

resources

object

Requested compute resources. Omitted fields resolve to deployment defaults at admission, and the resolved shape is echoed on every Sandbox response. A GPU request is rejected with 422 unsupported_capability when the deployment cannot schedule accelerators.

Show child attributes

command

string[]

Argv that replaces the image's own entrypoint as the sandbox's first process. Omit it to run the image's ENTRYPOINT/CMD unchanged, which is what an image built to hold itself open wants. Supply it for an image whose entrypoint runs a task and exits, such as a base OS image or a build tool: a sandbox is something you attach to, and it lives only as long as its first process. The argv is executed directly rather than through a shell, so pipes and redirection belong inside a command you name explicitly. The executable must not be empty; at most 256 entries, each at most 4096 characters.

workspace_capacity_gib

integer<uint32>

Durable workspace capacity in whole GiB. A root create may omit it to use the deployment default; a snapshot create inherits the snapshot-time value. A legacy snapshot whose capacity predates stamping requires an explicit value. This field is valid only with durable storage; standard storage has no persistent workspace claim.

Required range: x >= 1

placement_class

enum<string>

Capacity posture for this sandbox. Omit it to use standard placement.

Available options:

standard,

non_preemptible

idle_timeout_seconds

integer<uint32>

Idle duration in seconds after which a running sandbox is stopped. Omit it to use the deployment default; when the deployment has no default, idle stopping is disabled. Values are from 60 through 86400.

Required range: 60 <= x <= 86400

shared_filesystems

object[]

Deployment-registered shared filesystems to mount. Shared filesystems are external to this sandbox's snapshots; durable storage is required for the sandbox's private runtime state.

Show child attributes

network_access

enum<string>

Outbound-network posture. Omit it to use public access.

Available options:

public,

gateway_only,

none

Response

Accepted

string

required

The new sandbox id. Poll GetSandbox with this id for observed lifecycle state.

request_state

enum<string>

required

The accepted mutation-request state, distinct from observed sandbox lifecycle state.

Available options:

requested

run_id

string

required

The ambient run that receives telemetry captured for this sandbox. An idempotent create retry returns the same run id.

AnnotationSchemaService

MetaService

FeedbackService

ProjectService

RunService

SandboxService

SecretService

AnnotationService

TelemetryViewService

UsageService

VolumeService

IdentityService

WorkloadService

Post v1sandboxes

Authorizations

Headers

Body

Response