Getting started

Zeish has two planes. The control plane owns organizations, API keys, templates, sandboxes, resources, permissions, and lifecycle state. The data plane is the sandbox runtime, reached through short-lived credentials issued by the control plane.

A sandbox runs in a hardware-isolated MicroVM with its own Linux kernel. Firecracker is the default driver. Cloud Hypervisor is available when a node advertises it. The guest sandboxd service handles commands, files, terminal sessions, screenshots, and desktop actions without exposing the host control process.

Creates and lifecycle actions are asynchronous. Create a sandbox, wait for running, request data-plane access, then run work. Snapshots and clones let you fan out from a prepared environment instead of repeating setup.

Create a standalone API key in the dashboard, choose a template, and set ZEISH_API_KEY. The public API currently provisions in the bremen region. A templateId is required unless you configure defaultTemplateId in the SDK.

The session client waits for the sandbox data plane and refreshes its short-lived credential as needed. Use it for agent workflows that need commands, files, desktop actions, and lifecycle operations from one object.

The SDK default host is not the production Zeish host. Set baseUrl explicitly so the client calls https://api.zei.sh/api/v1.

1npm install @zeish/computesdk-provider23import { createZeishSandboxClient } from "@zeish/computesdk-provider";45const client = createZeishSandboxClient({6  apiKey: process.env.ZEISH_API_KEY!,7  defaultTemplateId: process.env.ZEISH_TEMPLATE_ID!,8  baseUrl: "https://api.zei.sh/api/v1",9});1011const sandbox = await client.create({ name: "first-run" });12await sandbox.waitForAccess();1314const result = await sandbox.run("uname -a");15console.log(result.stdout);1617await sandbox.destroy();

Create API keys from the dashboard's Limits page. A new key is shown once, stored as a hash, and starts with zeish_live_. Send it as X-API-Key for REST. Authorization: Bearer also works for public API requests.

New keys are standalone and use the organization and user that created them.

API keys are server credentials. Keep them out of browser bundles, logs, shell history, and source control. Use the smallest permission set that fits the integration: MACHINE_READ, MACHINE_CREATE, MACHINE_UPDATE, MACHINE_DELETE, and ORG_MANAGE.

1export ZEISH_API_KEY="zeish_live_..."23curl https://api.zei.sh/api/v1/public/sandboxes   -H "X-API-Key: $ZEISH_API_KEY"

Install a published release from https://api.zei.sh/api/v1/cli/versions. The binary also supports the aliases zctl and zc.

Use auth login for browser OAuth with PKCE, or set ZEISH_API_KEY for automation. The default API URL is https://api.zei.sh. OAuth state is stored under the zeish config directory with mode 0600.

Commands return JSON. The api escape hatch accepts any authenticated method and path. Data-plane commands obtain a scoped access token automatically, then use sandboxd gRPC or HTTP. Secret values come from stdin by default or from --value-file.

1zeishctl auth login2zeishctl sandboxes create agent-run --template-id TEMPLATE_ID3zeishctl sandboxes exec SANDBOX_ID -- echo hello4zeishctl sandboxes files SANDBOX_ID read /workspace/output.json5zeishctl sandboxes shell SANDBOX_ID6zeishctl sandboxes ssh SANDBOX_ID7zeishctl sandboxes snapshots SANDBOX_ID create before-deploy8zeishctl secrets create API_TOKEN --provider-reference secret/data/api-token < token.txt9zeishctl completion zsh > ~/.zsh/completions/_zeishctl10zeishctl upgrade