Platform capabilities

Ingress is declared with mode raw_l4, protocol tcp or udp, internalPort, and an optional externalPort. externalPort defaults to internalPort. Ports must be between 1 and 65535, and each protocol/external-port pair can appear only once.

There are two access policies. org is the default and limits access to matching organization credentials. public requires no authentication, so anyone with the endpoint can connect. A legacy private value is normalized to org. No cross-organization private tier exists.

Declare ingress when creating a sandbox or add a port later with POST /ports. Change its tier with PUT /ports/:port/share. Public port exposure is separate from preview-code lifetime.

1const sandbox = await api.createSandbox({2  name: "web-and-db",3  templateId: process.env.ZEISH_TEMPLATE_ID!,4  ingress: [5    { mode: "raw_l4", protocol: "tcp", internalPort: 3000 },6    {7      mode: "raw_l4",8      protocol: "tcp",9      internalPort: 5432,10      accessPolicy: "org",11    },12    {13      mode: "raw_l4",14      protocol: "udp",15      internalPort: 27015,16      externalPort: 27015,17    },18  ],19});2021await api.addPort(sandbox.id, {22  internalPort: 8080,23  protocol: "tcp",24  accessPolicy: "public",25});

POST /public/sandboxes/:sandboxId/preview-codes mints a time-limited code for a declared port. ttl_seconds defaults to 300 and accepts values from 1 through 3600. The response includes url, handoff_url, base_url, code, and expires_at.

Open url or handoff_url in a real browser. It is a single-use cookie handoff. For fetch, WebSocket, Playwright, or Chrome CDP, use base_url with Authorization: Bearer <code>. Do not append paths to the browser handoff URL.

The SDK normalizes the response to url, handoffUrl, baseUrl, token, headers, and expires_at. fetchPreviewJsonVersion and resolveCdpEndpoint handle Chrome's loopback WebSocket URL and preview authentication.

1const preview = await api.createPreviewCode(sandboxId, {2  port: 9222,3  ttl_seconds: 3600,4});56const version = await fetchPreviewJsonVersion(preview);7const endpoint = resolveCdpEndpoint({8  preview,9  webSocketDebuggerUrl: String(version.webSocketDebuggerUrl),10});1112// Playwright: chromium.connectOverCDP(endpoint.wsUrl, {13//   headers: endpoint.headers,14// });

POST /public/sandboxes/:sandboxId/tunnel-access returns ws_url, token, and expires_at. The token defaults to 60 seconds and accepts values from 1 through 3600. It grants tunnel:connect access to the sandbox's exposed TCP ports.

The tunnel WebSocket terminates at proxyd and dials the sandbox backend directly. This supports protocols such as Chrome CDP and database wire protocols that can reject a forwarded public Host header.

The SDK includes createTunnelBridge and createCdpTunnelBridge. Both bind locally to loopback only. Treat the local bridge as an unauthenticated capability while it is running and close it as soon as the operation ends.

1import {2  createTunnelBridge,3  TUNNEL_ACCESS_TTL_AGENT,4} from "@zeish/computesdk-provider";56const access = await api.createTunnelAccess(sandboxId, {7  ttl_seconds: TUNNEL_ACCESS_TTL_AGENT,8});9const bridge = await createTunnelBridge(access, 5432);1011console.log("database endpoint:", bridge.httpUrl);12// Connect your TCP client to bridge.localPort.1314await bridge.close();

Secrets are organization resources. Create, list, view, edit, and delete them with ORG_MANAGE. Values are never returned by list, while get returns the value and is audited with no-store response headers. The current configured provider is Vault. AWS Secrets Manager and GCP Secret Manager require a deployment with those providers configured.

Create a grant for a sandbox with a target of env or file. Environment names must be valid shell variable names. File targets must be below /run/secrets. A grant can apply at startup or command time. A sandbox create request can include the same refs under secretInjection.

Secret leases are short-lived and scoped to the organization, sandbox, exact secret IDs, target names, operation, expiry, and nonce. Secret values and provider credentials are not persisted in sandbox records, snapshots, or ordinary runtime responses.

1curl -X POST https://api.zei.sh/api/v1/public/secrets   -H "X-API-Key: $ZEISH_API_KEY"   -H "Content-Type: application/json"   -d '{2    "name": "github-token",3    "provider": "vault",4    "providerReference": "secret/data/ci/github",5    "providerKey": "token",6    "format": "plaintext",7    "value": "replace-me"8  }'910# Advanced routes11# POST /public/secrets/:secretId/grants12# POST /public/secrets/:sandboxId/leases

GET /public/sandboxes/:sandboxId/logs returns captured output. Filter by service or source and set a bounded limit. Sources are boot, memory, and app. GET /events returns lifecycle events with status, source, timestamp, and an optional message.

Logs and events are read-only control-plane calls and require MACHINE_READ. They are useful for polling state transitions, diagnosing failed provisioning, and correlating workload output with a run label.

The current public API returns bounded history, not an unbounded live stream. Persist only the data your retention policy allows.

1const logs = await api.listLogs(sandboxId, {2  limit: 100,3  source: "app",4});5const events = await api.listEvents(sandboxId, { limit: 100 });67console.log({ logs, events });

Firecracker is the default runtime and the broadest compatibility target. Cloud Hypervisor uses the same sandbox lifecycle surface and is enabled per node. Availability depends on the node and its advertised capabilities.

The runtime is supervised independently from the node orchestrator process. A process crash can recover the same sandbox identity and durable state. This does not promise migration when an entire host goes offline.

Persistent volumes and Windows guests are not available on Cloud Hypervisor today. Treat cross-node failover as unsupported and design agents to handle failed or terminal statuses.