> For the complete documentation index, see [llms.txt](https://docs.ai.neevcloud.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ai.neevcloud.com/api-reference/ai-agent/sandboxes.md).
# Sandboxes
## GET /api/v1beta1/orgs/{org\_id}/projects/{project\_id}/sandboxes
> List sandboxes in a project
```json
{"openapi":"3.0.3","info":{"title":"AI Agent Service API","version":"0.2.0"},"servers":[{"url":"https://api.ai.neevcloud.com/agent","description":"Consolidated public API gateway"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"OrgID":{"name":"org_id","in":"path","required":true,"description":"Organization identifier.","schema":{"type":"string"}},"ProjectID":{"name":"project_id","in":"path","required":true,"description":"Project identifier.","schema":{"type":"string"}},"Page":{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},"Limit":{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}},"schemas":{"SandboxListResponse":{"type":"object","required":["items","total","page","limit"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Sandbox"}},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"}}},"Sandbox":{"type":"object","required":["id","org_id","project_id","name","region","image","phase","replicas","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string"},"project_id":{"type":"string"},"name":{"type":"string"},"region":{"type":"string","description":"Region where the sandbox runs."},"image":{"type":"string"},"command":{"type":"array","items":{"type":"string"}},"env":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"resources":{"$ref":"#/components/schemas/SandboxResources"},"phase":{"$ref":"#/components/schemas/SandboxPhase"},"connect_url":{"type":"string","nullable":true,"description":"Public URL the SDK calls (API key + X-Sandbox-Id). null when not configured."},"replicas":{"type":"integer","minimum":0,"maximum":1,"description":"0 = paused, 1 = running."},"egress":{"allOf":[{"$ref":"#/components/schemas/SandboxEgressConfig"}],"nullable":true},"sandbox_template_id":{"type":"string","nullable":true,"description":"Catalogue template id from create when one was provided; null otherwise."},"created_by":{"type":"string","nullable":true,"description":"Identity that created the sandbox (user id, or API key id for key-authenticated calls); null for sandboxes created before this was recorded."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"EnvVar":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}},"SandboxResources":{"type":"object","description":"Sandbox compute size. Omitted fields use the platform default.\n","properties":{"cpu":{"type":"number","minimum":0.5,"maximum":8,"multipleOf":0.5,"description":"vCPUs. Multiples of 0.5, from 0.5 to 8."},"memory_gb":{"type":"integer","minimum":1,"maximum":16,"description":"Memory in GB, from 1 to 16."},"disk_gb":{"type":"integer","minimum":10,"maximum":100,"multipleOf":10,"description":"Ephemeral disk in GB. Multiples of 10, from 10 to 100."}}},"SandboxPhase":{"type":"string","enum":["Pending","Ready","NotReady","Unknown","Paused"]},"SandboxEgressConfig":{"type":"object","description":"Network egress configuration rules for the sandbox.","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["deny_all","allow_list"],"default":"deny_all","description":"The egress mode. deny_all blocks all egress. allow_list restricts egress to the specified allowed destinations."},"allow_internet":{"type":"boolean","description":"Escape hatch: if true, allows 0.0.0.0/0 (the entire internet). Strictly audit-logged.","default":false},"allow":{"type":"array","description":"List of egress rules for host/IP destinations to allow.","items":{"$ref":"#/components/schemas/SandboxEgressRule"}}}},"SandboxEgressRule":{"type":"object","description":"Individual egress rule specifying allowed destination host.","additionalProperties":false,"required":["host"],"properties":{"host":{"type":"string","description":"IP address, CIDR block, or domain name"},"ports":{"type":"array","items":{"type":"integer"}},"protocol":{"type":"string","enum":["TCP","UDP"]}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"details":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1beta1/orgs/{org_id}/projects/{project_id}/sandboxes":{"get":{"tags":["Sandboxes"],"summary":"List sandboxes in a project","operationId":"listSandboxes","parameters":[{"$ref":"#/components/parameters/OrgID"},{"$ref":"#/components/parameters/ProjectID"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Paginated list of sandboxes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```
## POST /api/v1beta1/orgs/{org\_id}/projects/{project\_id}/sandboxes
> Create a sandbox
```json
{"openapi":"3.0.3","info":{"title":"AI Agent Service API","version":"0.2.0"},"servers":[{"url":"https://api.ai.neevcloud.com/agent","description":"Consolidated public API gateway"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"OrgID":{"name":"org_id","in":"path","required":true,"description":"Organization identifier.","schema":{"type":"string"}},"ProjectID":{"name":"project_id","in":"path","required":true,"description":"Project identifier.","schema":{"type":"string"}}},"schemas":{"CreateSandboxRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":63,"pattern":"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$","description":"Sandbox name. Used verbatim as the Sandbox CR name and as a routing\nlabel, so it must be a valid DNS-1123 label: lowercase alphanumeric\ncharacters or '-', starting and ending with an alphanumeric, max 63\ncharacters.\n"},"region":{"type":"string","description":"Region to provision in; omit to use the platform default."},"env":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"resources":{"$ref":"#/components/schemas/SandboxResources"},"egress":{"$ref":"#/components/schemas/SandboxEgressConfig"},"sandbox_template_id":{"type":"string","minLength":1,"pattern":"^sb-[a-zA-Z0-9-]+$","description":"Catalogue template id (e.g. sb-ubuntu-26-04-minimal). The server\nvalidates the template exists and is active, then provisions the\nsandbox image and command from that template.\n"},"from_snapshot":{"type":"string","format":"uuid","nullable":true,"description":"When set, the new sandbox is restored from this snapshot instead of\ncold-starting from the image. Snapshot must belong to the same\nproject. Sizing and region must match the snapshot's origin.\n"}}},"EnvVar":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}},"SandboxResources":{"type":"object","description":"Sandbox compute size. Omitted fields use the platform default.\n","properties":{"cpu":{"type":"number","minimum":0.5,"maximum":8,"multipleOf":0.5,"description":"vCPUs. Multiples of 0.5, from 0.5 to 8."},"memory_gb":{"type":"integer","minimum":1,"maximum":16,"description":"Memory in GB, from 1 to 16."},"disk_gb":{"type":"integer","minimum":10,"maximum":100,"multipleOf":10,"description":"Ephemeral disk in GB. Multiples of 10, from 10 to 100."}}},"SandboxEgressConfig":{"type":"object","description":"Network egress configuration rules for the sandbox.","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["deny_all","allow_list"],"default":"deny_all","description":"The egress mode. deny_all blocks all egress. allow_list restricts egress to the specified allowed destinations."},"allow_internet":{"type":"boolean","description":"Escape hatch: if true, allows 0.0.0.0/0 (the entire internet). Strictly audit-logged.","default":false},"allow":{"type":"array","description":"List of egress rules for host/IP destinations to allow.","items":{"$ref":"#/components/schemas/SandboxEgressRule"}}}},"SandboxEgressRule":{"type":"object","description":"Individual egress rule specifying allowed destination host.","additionalProperties":false,"required":["host"],"properties":{"host":{"type":"string","description":"IP address, CIDR block, or domain name"},"ports":{"type":"array","items":{"type":"integer"}},"protocol":{"type":"string","enum":["TCP","UDP"]}}},"Sandbox":{"type":"object","required":["id","org_id","project_id","name","region","image","phase","replicas","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string"},"project_id":{"type":"string"},"name":{"type":"string"},"region":{"type":"string","description":"Region where the sandbox runs."},"image":{"type":"string"},"command":{"type":"array","items":{"type":"string"}},"env":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"resources":{"$ref":"#/components/schemas/SandboxResources"},"phase":{"$ref":"#/components/schemas/SandboxPhase"},"connect_url":{"type":"string","nullable":true,"description":"Public URL the SDK calls (API key + X-Sandbox-Id). null when not configured."},"replicas":{"type":"integer","minimum":0,"maximum":1,"description":"0 = paused, 1 = running."},"egress":{"allOf":[{"$ref":"#/components/schemas/SandboxEgressConfig"}],"nullable":true},"sandbox_template_id":{"type":"string","nullable":true,"description":"Catalogue template id from create when one was provided; null otherwise."},"created_by":{"type":"string","nullable":true,"description":"Identity that created the sandbox (user id, or API key id for key-authenticated calls); null for sandboxes created before this was recorded."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"SandboxPhase":{"type":"string","enum":["Pending","Ready","NotReady","Unknown","Paused"]},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"details":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Conflict":{"description":"Resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1beta1/orgs/{org_id}/projects/{project_id}/sandboxes":{"post":{"tags":["Sandboxes"],"summary":"Create a sandbox","operationId":"createSandbox","parameters":[{"$ref":"#/components/parameters/OrgID"},{"$ref":"#/components/parameters/ProjectID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSandboxRequest"}}}},"responses":{"201":{"description":"Sandbox accepted; may still be provisioning (check `phase`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sandbox"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```
## GET /api/v1beta1/orgs/{org\_id}/projects/{project\_id}/sandboxes/{sandbox\_id}
> Get a sandbox by ID
```json
{"openapi":"3.0.3","info":{"title":"AI Agent Service API","version":"0.2.0"},"servers":[{"url":"https://api.ai.neevcloud.com/agent","description":"Consolidated public API gateway"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"OrgID":{"name":"org_id","in":"path","required":true,"description":"Organization identifier.","schema":{"type":"string"}},"ProjectID":{"name":"project_id","in":"path","required":true,"description":"Project identifier.","schema":{"type":"string"}},"SandboxID":{"name":"sandbox_id","in":"path","required":true,"description":"Sandbox UUID.","schema":{"type":"string","format":"uuid"}}},"schemas":{"Sandbox":{"type":"object","required":["id","org_id","project_id","name","region","image","phase","replicas","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string"},"project_id":{"type":"string"},"name":{"type":"string"},"region":{"type":"string","description":"Region where the sandbox runs."},"image":{"type":"string"},"command":{"type":"array","items":{"type":"string"}},"env":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"resources":{"$ref":"#/components/schemas/SandboxResources"},"phase":{"$ref":"#/components/schemas/SandboxPhase"},"connect_url":{"type":"string","nullable":true,"description":"Public URL the SDK calls (API key + X-Sandbox-Id). null when not configured."},"replicas":{"type":"integer","minimum":0,"maximum":1,"description":"0 = paused, 1 = running."},"egress":{"allOf":[{"$ref":"#/components/schemas/SandboxEgressConfig"}],"nullable":true},"sandbox_template_id":{"type":"string","nullable":true,"description":"Catalogue template id from create when one was provided; null otherwise."},"created_by":{"type":"string","nullable":true,"description":"Identity that created the sandbox (user id, or API key id for key-authenticated calls); null for sandboxes created before this was recorded."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"EnvVar":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}},"SandboxResources":{"type":"object","description":"Sandbox compute size. Omitted fields use the platform default.\n","properties":{"cpu":{"type":"number","minimum":0.5,"maximum":8,"multipleOf":0.5,"description":"vCPUs. Multiples of 0.5, from 0.5 to 8."},"memory_gb":{"type":"integer","minimum":1,"maximum":16,"description":"Memory in GB, from 1 to 16."},"disk_gb":{"type":"integer","minimum":10,"maximum":100,"multipleOf":10,"description":"Ephemeral disk in GB. Multiples of 10, from 10 to 100."}}},"SandboxPhase":{"type":"string","enum":["Pending","Ready","NotReady","Unknown","Paused"]},"SandboxEgressConfig":{"type":"object","description":"Network egress configuration rules for the sandbox.","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["deny_all","allow_list"],"default":"deny_all","description":"The egress mode. deny_all blocks all egress. allow_list restricts egress to the specified allowed destinations."},"allow_internet":{"type":"boolean","description":"Escape hatch: if true, allows 0.0.0.0/0 (the entire internet). Strictly audit-logged.","default":false},"allow":{"type":"array","description":"List of egress rules for host/IP destinations to allow.","items":{"$ref":"#/components/schemas/SandboxEgressRule"}}}},"SandboxEgressRule":{"type":"object","description":"Individual egress rule specifying allowed destination host.","additionalProperties":false,"required":["host"],"properties":{"host":{"type":"string","description":"IP address, CIDR block, or domain name"},"ports":{"type":"array","items":{"type":"integer"}},"protocol":{"type":"string","enum":["TCP","UDP"]}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"details":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1beta1/orgs/{org_id}/projects/{project_id}/sandboxes/{sandbox_id}":{"get":{"tags":["Sandboxes"],"summary":"Get a sandbox by ID","operationId":"getSandbox","parameters":[{"$ref":"#/components/parameters/OrgID"},{"$ref":"#/components/parameters/ProjectID"},{"$ref":"#/components/parameters/SandboxID"}],"responses":{"200":{"description":"Sandbox details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sandbox"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```
## DELETE /api/v1beta1/orgs/{org\_id}/projects/{project\_id}/sandboxes/{sandbox\_id}
> Delete a sandbox
```json
{"openapi":"3.0.3","info":{"title":"AI Agent Service API","version":"0.2.0"},"servers":[{"url":"https://api.ai.neevcloud.com/agent","description":"Consolidated public API gateway"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"OrgID":{"name":"org_id","in":"path","required":true,"description":"Organization identifier.","schema":{"type":"string"}},"ProjectID":{"name":"project_id","in":"path","required":true,"description":"Project identifier.","schema":{"type":"string"}},"SandboxID":{"name":"sandbox_id","in":"path","required":true,"description":"Sandbox UUID.","schema":{"type":"string","format":"uuid"}}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"details":{"type":"string"}}}}},"paths":{"/api/v1beta1/orgs/{org_id}/projects/{project_id}/sandboxes/{sandbox_id}":{"delete":{"tags":["Sandboxes"],"summary":"Delete a sandbox","operationId":"deleteSandbox","parameters":[{"$ref":"#/components/parameters/OrgID"},{"$ref":"#/components/parameters/ProjectID"},{"$ref":"#/components/parameters/SandboxID"}],"responses":{"204":{"description":"Sandbox deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```
## Pause a sandbox (stop billable runtime; preserve disks)
> When \`preserve\_memory\` is true the sandbox's full state (process memory\
> \+ filesystem) is captured as an implicit snapshot before the pod is\
> terminated. The snapshot is retained for the duration of the paused\
> state and consumed automatically on the next \`resume\`. When false\
> (default) the existing volume-only behaviour applies.
```json
{"openapi":"3.0.3","info":{"title":"AI Agent Service API","version":"0.2.0"},"servers":[{"url":"https://api.ai.neevcloud.com/agent","description":"Consolidated public API gateway"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"OrgID":{"name":"org_id","in":"path","required":true,"description":"Organization identifier.","schema":{"type":"string"}},"ProjectID":{"name":"project_id","in":"path","required":true,"description":"Project identifier.","schema":{"type":"string"}},"SandboxID":{"name":"sandbox_id","in":"path","required":true,"description":"Sandbox UUID.","schema":{"type":"string","format":"uuid"}}},"schemas":{"PauseSandboxRequest":{"type":"object","description":"Optional body for the pause endpoint.","properties":{"preserve_memory":{"type":"boolean","default":true,"description":"When true, capture FS+process memory as an implicit snapshot before\nterminating the pod. The snapshot is auto-consumed on the next resume.\n"}}},"Sandbox":{"type":"object","required":["id","org_id","project_id","name","region","image","phase","replicas","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string"},"project_id":{"type":"string"},"name":{"type":"string"},"region":{"type":"string","description":"Region where the sandbox runs."},"image":{"type":"string"},"command":{"type":"array","items":{"type":"string"}},"env":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"resources":{"$ref":"#/components/schemas/SandboxResources"},"phase":{"$ref":"#/components/schemas/SandboxPhase"},"connect_url":{"type":"string","nullable":true,"description":"Public URL the SDK calls (API key + X-Sandbox-Id). null when not configured."},"replicas":{"type":"integer","minimum":0,"maximum":1,"description":"0 = paused, 1 = running."},"egress":{"allOf":[{"$ref":"#/components/schemas/SandboxEgressConfig"}],"nullable":true},"sandbox_template_id":{"type":"string","nullable":true,"description":"Catalogue template id from create when one was provided; null otherwise."},"created_by":{"type":"string","nullable":true,"description":"Identity that created the sandbox (user id, or API key id for key-authenticated calls); null for sandboxes created before this was recorded."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"EnvVar":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}},"SandboxResources":{"type":"object","description":"Sandbox compute size. Omitted fields use the platform default.\n","properties":{"cpu":{"type":"number","minimum":0.5,"maximum":8,"multipleOf":0.5,"description":"vCPUs. Multiples of 0.5, from 0.5 to 8."},"memory_gb":{"type":"integer","minimum":1,"maximum":16,"description":"Memory in GB, from 1 to 16."},"disk_gb":{"type":"integer","minimum":10,"maximum":100,"multipleOf":10,"description":"Ephemeral disk in GB. Multiples of 10, from 10 to 100."}}},"SandboxPhase":{"type":"string","enum":["Pending","Ready","NotReady","Unknown","Paused"]},"SandboxEgressConfig":{"type":"object","description":"Network egress configuration rules for the sandbox.","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["deny_all","allow_list"],"default":"deny_all","description":"The egress mode. deny_all blocks all egress. allow_list restricts egress to the specified allowed destinations."},"allow_internet":{"type":"boolean","description":"Escape hatch: if true, allows 0.0.0.0/0 (the entire internet). Strictly audit-logged.","default":false},"allow":{"type":"array","description":"List of egress rules for host/IP destinations to allow.","items":{"$ref":"#/components/schemas/SandboxEgressRule"}}}},"SandboxEgressRule":{"type":"object","description":"Individual egress rule specifying allowed destination host.","additionalProperties":false,"required":["host"],"properties":{"host":{"type":"string","description":"IP address, CIDR block, or domain name"},"ports":{"type":"array","items":{"type":"integer"}},"protocol":{"type":"string","enum":["TCP","UDP"]}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"details":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1beta1/orgs/{org_id}/projects/{project_id}/sandboxes/{sandbox_id}/pause":{"post":{"tags":["Sandboxes"],"summary":"Pause a sandbox (stop billable runtime; preserve disks)","description":"When `preserve_memory` is true the sandbox's full state (process memory\n+ filesystem) is captured as an implicit snapshot before the pod is\nterminated. The snapshot is retained for the duration of the paused\nstate and consumed automatically on the next `resume`. When false\n(default) the existing volume-only behaviour applies.\n","operationId":"pauseSandbox","parameters":[{"$ref":"#/components/parameters/OrgID"},{"$ref":"#/components/parameters/ProjectID"},{"$ref":"#/components/parameters/SandboxID"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PauseSandboxRequest"}}}},"responses":{"200":{"description":"Sandbox paused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sandbox"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```
## Resume a paused sandbox
> Restores a paused sandbox. When the sandbox was paused with\
> \`preserve\_memory=true\` it resumes from the implicit memory snapshot;\
> otherwise it cold-starts from the original image.
```json
{"openapi":"3.0.3","info":{"title":"AI Agent Service API","version":"0.2.0"},"servers":[{"url":"https://api.ai.neevcloud.com/agent","description":"Consolidated public API gateway"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"OrgID":{"name":"org_id","in":"path","required":true,"description":"Organization identifier.","schema":{"type":"string"}},"ProjectID":{"name":"project_id","in":"path","required":true,"description":"Project identifier.","schema":{"type":"string"}},"SandboxID":{"name":"sandbox_id","in":"path","required":true,"description":"Sandbox UUID.","schema":{"type":"string","format":"uuid"}}},"schemas":{"Sandbox":{"type":"object","required":["id","org_id","project_id","name","region","image","phase","replicas","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string"},"project_id":{"type":"string"},"name":{"type":"string"},"region":{"type":"string","description":"Region where the sandbox runs."},"image":{"type":"string"},"command":{"type":"array","items":{"type":"string"}},"env":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"resources":{"$ref":"#/components/schemas/SandboxResources"},"phase":{"$ref":"#/components/schemas/SandboxPhase"},"connect_url":{"type":"string","nullable":true,"description":"Public URL the SDK calls (API key + X-Sandbox-Id). null when not configured."},"replicas":{"type":"integer","minimum":0,"maximum":1,"description":"0 = paused, 1 = running."},"egress":{"allOf":[{"$ref":"#/components/schemas/SandboxEgressConfig"}],"nullable":true},"sandbox_template_id":{"type":"string","nullable":true,"description":"Catalogue template id from create when one was provided; null otherwise."},"created_by":{"type":"string","nullable":true,"description":"Identity that created the sandbox (user id, or API key id for key-authenticated calls); null for sandboxes created before this was recorded."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"EnvVar":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}},"SandboxResources":{"type":"object","description":"Sandbox compute size. Omitted fields use the platform default.\n","properties":{"cpu":{"type":"number","minimum":0.5,"maximum":8,"multipleOf":0.5,"description":"vCPUs. Multiples of 0.5, from 0.5 to 8."},"memory_gb":{"type":"integer","minimum":1,"maximum":16,"description":"Memory in GB, from 1 to 16."},"disk_gb":{"type":"integer","minimum":10,"maximum":100,"multipleOf":10,"description":"Ephemeral disk in GB. Multiples of 10, from 10 to 100."}}},"SandboxPhase":{"type":"string","enum":["Pending","Ready","NotReady","Unknown","Paused"]},"SandboxEgressConfig":{"type":"object","description":"Network egress configuration rules for the sandbox.","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["deny_all","allow_list"],"default":"deny_all","description":"The egress mode. deny_all blocks all egress. allow_list restricts egress to the specified allowed destinations."},"allow_internet":{"type":"boolean","description":"Escape hatch: if true, allows 0.0.0.0/0 (the entire internet). Strictly audit-logged.","default":false},"allow":{"type":"array","description":"List of egress rules for host/IP destinations to allow.","items":{"$ref":"#/components/schemas/SandboxEgressRule"}}}},"SandboxEgressRule":{"type":"object","description":"Individual egress rule specifying allowed destination host.","additionalProperties":false,"required":["host"],"properties":{"host":{"type":"string","description":"IP address, CIDR block, or domain name"},"ports":{"type":"array","items":{"type":"integer"}},"protocol":{"type":"string","enum":["TCP","UDP"]}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"details":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1beta1/orgs/{org_id}/projects/{project_id}/sandboxes/{sandbox_id}/resume":{"post":{"tags":["Sandboxes"],"summary":"Resume a paused sandbox","description":"Restores a paused sandbox. When the sandbox was paused with\n`preserve_memory=true` it resumes from the implicit memory snapshot;\notherwise it cold-starts from the original image.\n","operationId":"resumeSandbox","parameters":[{"$ref":"#/components/parameters/OrgID"},{"$ref":"#/components/parameters/ProjectID"},{"$ref":"#/components/parameters/SandboxID"}],"responses":{"200":{"description":"Sandbox resumed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sandbox"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```
## Read live health metrics for a sandbox
> Returns the bounded metric set for one sandbox (CPU / memory / disk\
> plus lifecycle and rate series). \`from\` / \`to\` / \`step\` are optional\
> and default to the last hour; the full v1 metric set is always\
> returned (no metric selector).
```json
{"openapi":"3.0.3","info":{"title":"AI Agent Service API","version":"0.2.0"},"servers":[{"url":"https://api.ai.neevcloud.com/agent","description":"Consolidated public API gateway"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"OrgID":{"name":"org_id","in":"path","required":true,"description":"Organization identifier.","schema":{"type":"string"}},"ProjectID":{"name":"project_id","in":"path","required":true,"description":"Project identifier.","schema":{"type":"string"}},"SandboxID":{"name":"sandbox_id","in":"path","required":true,"description":"Sandbox UUID.","schema":{"type":"string","format":"uuid"}}},"schemas":{"SandboxMetricsResponse":{"type":"object","required":["sandbox_id","from","to","step","series"],"properties":{"sandbox_id":{"type":"string","format":"uuid"},"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"step":{"type":"string","description":"Resolution actually used after server-side clamping."},"series":{"type":"array","items":{"$ref":"#/components/schemas/MetricSeries"}}}},"MetricSeries":{"type":"object","required":["metric","points"],"properties":{"metric":{"type":"string","description":"Stable metric key from the v1 catalogue (e.g. \"cpu_usage_cores\", \"memory_usage_bytes\")."},"unit":{"type":"string","description":"Unit of the values (e.g. \"cores\", \"bytes\", \"count\", \"ratio\")."},"points":{"type":"array","description":"Time-ordered [unix_seconds, value] pairs. Empty when the sandbox emitted no samples in the window.","items":{"type":"array","items":{"type":"number","format":"double"}}}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"details":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1beta1/orgs/{org_id}/projects/{project_id}/sandboxes/{sandbox_id}/metrics":{"get":{"tags":["Sandboxes"],"summary":"Read live health metrics for a sandbox","description":"Returns the bounded metric set for one sandbox (CPU / memory / disk\nplus lifecycle and rate series). `from` / `to` / `step` are optional\nand default to the last hour; the full v1 metric set is always\nreturned (no metric selector).\n","operationId":"getSandboxMetrics","parameters":[{"$ref":"#/components/parameters/OrgID"},{"$ref":"#/components/parameters/ProjectID"},{"$ref":"#/components/parameters/SandboxID"},{"name":"from","in":"query","required":false,"description":"Start of the window (RFC3339). Defaults to one hour before `to`.","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"description":"End of the window (RFC3339). Defaults to now.","schema":{"type":"string","format":"date-time"}},{"name":"step","in":"query","required":false,"description":"Resolution (e.g. \"60s\", \"5m\"). Server clamps to a sane range.","schema":{"type":"string"}}],"responses":{"200":{"description":"Metric series for the sandbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxMetricsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.ai.neevcloud.com/api-reference/ai-agent/sandboxes.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.