@lizard-build/sdk 0.1.40 → 0.1.41

package/README.md

@@ -1,293 +1,93 @@
-# Lizard SDK
+# Lizard TypeScript SDK
 
-TypeScript and Python clients for Lizard apps, managed databases, storage and Linux sandboxes.
-
-The current platform runs sandboxes on Kubernetes. Persistent volumes keep files across sandbox lifetimes. Pause, resume, fork and snapshot restore currently return HTTP 501; the SDK exposes those endpoints but does not promise state preservation.
-
-Requires Node.js 18+ or Python 3.10+. The optional `LizardCLI` adapter and `billing.payX402()` / `billing.pay_x402()` require Lizard CLI 4.0.8+ on PATH.
-
-See [CLI coverage and migration notes](https://github.com/lizard-build/lizard-sdk/blob/main/docs/cli-parity.md) for native methods, CLI-backed operations and test scope.
+Run commands, work with files and execute code in Linux sandboxes on Kubernetes. The SDK also manages Lizard apps, databases, storage and projects.
 
 ## Install
 
-```bash
-# JavaScript / TypeScript
-npm install @lizard-build/sdk
-
-# Python
-pip install lizard-sdk
-```
-
-## Quickstart
-
-### JavaScript / TypeScript
-
-```ts
-import { Lizard } from '@lizard-build/sdk'
+Requires Node.js 18+.
 
-// A client is pinned to one project — sandboxes are billed per project, so a
-// project is required. It can be the project's ID, slug, or name.
-// apiKey defaults to the LIZARD_API_KEY env var.
-const lizard = new Lizard({ project: 'my-project' })
-
-// Boot a sandbox from the 'base' template (Debian + Node.js 26)
-const sandbox = await lizard.create('base')
-
-// Write a file directly into the sandbox filesystem
-await sandbox.fs.write('/app/server.js', `
-  const http = require('http')
-  http.createServer((_, res) => res.end('hello from Lizard')).listen(3000)
-`)
-
-// Execute a process inside the sandbox
-await sandbox.process.exec('node /app/server.js &')
-
-// Get a public HTTPS URL for port 3000 inside the sandbox
-const url = await sandbox.getHost(3000)
-console.log(`Live at https://${url}`)
-
-// Tear down the sandbox when done
-await sandbox.kill()
+```sh
+npm install @lizard-build/sdk
 ```
 
-### Python
-
-```python
-from lizard import Lizard
-
-# A client is pinned to one project — sandboxes are billed per project, so a
-# project is required (its ID, slug, or name). api_key defaults to LIZARD_API_KEY.
-lizard = Lizard(project="my-project")
-
-# Boot a Python sandbox from the 'code-interpreter-v1' template
-sandbox = lizard.create("code-interpreter-v1")
-
-# Write a script into the sandbox filesystem
-sandbox.fs.write("/app/main.py", """
-import http.server, socketserver
-
-class Handler(http.server.SimpleHTTPRequestHandler):
-    def do_GET(self):
-        self.send_response(200)
-        self.end_headers()
-        self.wfile.write(b"hello from Lizard")
+Create an API key and project at [lizard.build](https://lizard.build), then set:
 
-with socketserver.TCPServer(("", 3000), Handler) as httpd:
-    httpd.serve_forever()
-""")
-
-# Execute a process inside the sandbox
-sandbox.process.exec_("python /app/main.py &")
-
-print(f"Live at https://{sandbox.get_host(3000)}")
-
-sandbox.kill()
+```sh
+export LIZARD_API_KEY="your-api-key"
 ```
 
-## Persisting Work Across Sandboxes
-
-Sandboxes are **ephemeral**: killing one, or letting it hit its timeout, discards everything written inside it. State that has to outlive a sandbox goes on a **volume** — a separate disk mounted at `/workspace` that a later sandbox re-attaches.
-
-A volume is node-local, so it fixes the region too. You don't thread a region through both calls: the sandbox is placed wherever its volume already lives.
-
-```ts
-const vol = await lizard.volumes.getOrCreate('agent-scratch', { sizeGb: 10 })
-
-const first = await lizard.create('codex', { volumeName: 'agent-scratch' })
-await first.process.exec('pip install numpy pandas && echo "notes" > /workspace/notes.txt')
-await first.kill()          // sandbox gone, /workspace survives
-
-const second = await lizard.create('codex', { volumeName: 'agent-scratch' })
-console.log(await second.fs.read('/workspace/notes.txt'))   // "notes"
-```
+## Create a sandbox
 
-```python
-vol = lizard.volumes.get_or_create("agent-scratch", size_gb=10)
+Save this as `quickstart.mjs`. Replace `my-project` with your project's ID, slug or unique name, then run `node quickstart.mjs`.
 
-first = lizard.create("codex", volume_name="agent-scratch")
-first.process.exec_('echo "notes" > /workspace/notes.txt')
-first.kill()                # sandbox gone, /workspace survives
+```js
+import { Lizard } from '@lizard-build/sdk'
 
-second = lizard.create("codex", volume_name="agent-scratch")
-print(second.fs.read("/workspace/notes.txt"))   # "notes"
+const lizard = new Lizard({ project: 'my-project' })
+const sandbox = await lizard.create('base', { timeoutMs: 300_000 })
+
+try {
+  await sandbox.fs.write('/tmp/hello.txt', 'Hello from Lizard!')
+  const result = await sandbox.process.exec('cat /tmp/hello.txt')
+  if (result.exitCode !== 0) throw new Error(result.stderr)
+  console.log(result.stdout)
+} finally {
+  await sandbox.kill()
+}
 ```
 
-Note that only `/workspace` survives — installed packages and in-memory state do not. Bake tooling into a template instead of reinstalling it per sandbox.
+The package includes TypeScript declarations and ESM and CommonJS builds. For CommonJS, use `const { Lizard } = require('@lizard-build/sdk')` inside a program with an async entry point.
 
-> `pause()` / `resume()` exist on the client but are **not implemented** for the current runtime and always fail with HTTP 501. Use a volume.
+## Stream command output
 
-## Giving Each of Your Users Their Own Workspace
-
-If you are building on top of Lizard and your users each need isolated resources, give each one a workspace and an API key scoped to it. They get isolation from each other; you keep one bill.
+Inside the `try` block above:
 
 ```ts
-const lizard = new Lizard({ apiKey: process.env.LIZARD_API_KEY })
-
-const ws  = await lizard.workspaces.create({ name: `user-${userId}` })
-const prj = await lizard.projects.create({ workspaceId: ws.id, name: 'default' })
-const key = await lizard.apiKeys.create({ name: `user-${userId}`, workspaces: [ws.id] })
-
-// key.key is returned exactly once. Store it now.
-await db.users.update(userId, { lizardKey: key.key })
-```
-
-That key reaches nothing outside `ws`, and it cannot mint a broader one — the server rejects that with an exact subset check. So it is safe to hand to the user, and safe to put **inside a sandbox** so agent code can use the CLI as that user:
-
-```ts
-const sandbox = await Sandbox.create('codex', {
-  projectId: prj.id,
-  lizardToken: key.key,        // scoped — bounded if it leaks
+const result = await sandbox.process.exec('printf "hello\\n"', {
+  timeoutMs: 30_000,
+  onStdout: chunk => process.stdout.write(chunk),
+  onStderr: chunk => process.stderr.write(chunk),
 })
-await sandbox.process.exec('lizard volume list')   // sees only this workspace
+if (result.exitCode !== 0) throw new Error(result.stderr)
 ```
 
-```python
-ws = lizard.workspaces.create(name=f"user-{user_id}")
-prj = lizard.projects.create(workspace_id=ws.id, name="default")
-key = lizard.api_keys.create(name=f"user-{user_id}", workspaces=[ws.id])
-
-sandbox = Sandbox.create("codex", project_id=prj.id, lizard_token=key.key)
-sandbox.process.exec_("lizard volume list")
-```
-
-A key with **no** scope has full access to everything the creating account can reach — pass `workspaces` or `projects` unless you mean that.
-
-### What a scoped key deliberately cannot see
+## Run code
 
-Billing is account-level: one balance, one ledger, one set of saved cards, shared by every workspace. There is no per-workspace view of it, so a scoped key is refused outright (403 `ACCOUNT_SCOPE_REQUIRED`) on `lizard.billing.*` and on account-wide usage, and `whoami()` returns only identity plus the key's own scopes — not the account's email, balance or plan.
-
-That matters because of where these keys end up. A key you hand to a user, or inject into a sandbox with `lizardToken`, is readable by anything running there. It should not be a way to read your card details or spend against them.
-
-For per-workspace spend, use `lizard.metrics` — that is scoped, and is what you would bill a user from.
-
-## API
-
-### `new Lizard({ project, apiKey?, apiUrl?, timeoutMs? })`
-
-Create a client pinned to a project. Every sandbox is billed per project, so `project` is required — pass its ID, slug, or name (resolved to an ID on first use and cached). `apiKey` defaults to the `LIZARD_API_KEY` env var.
-
-```ts
-const lizard = new Lizard({ project: 'my-project' })
-const sandbox = await lizard.create('base')
-const sandbox = await lizard.create('code-interpreter-v1', { timeoutMs: 10 * 60 * 1000 })
-```
-
-### `Sandbox.create(template?, opts?)`
-
-Create a Lizard sandbox using a template such as `base` or `code-interpreter-v1`. Template availability depends on the platform and region. A project is required — pass `project` (ID, slug, or name) or an exact `projectId` in `opts`, or use a `Lizard` client, which pins one for you.
+`CodeSandbox` uses the `code-interpreter-v1` template by default. Code errors appear in `result.error`; request failures throw.
 
 ```ts
-const sandbox = await Sandbox.create('base', { project: 'my-project' })
-const sandbox = await Sandbox.create('code-interpreter-v1', { project: 'my-project', timeoutMs: 10 * 60 * 1000 })
+import { CodeSandbox } from '@lizard-build/sdk'
+
+const sandbox = await CodeSandbox.create({ project: 'my-project' })
+try {
+  const result = await sandbox.runCode('print(6 * 7)', {
+    language: 'python',
+    timeoutMs: 60_000,
+    onStdout: chunk => process.stdout.write(chunk),
+  })
+  if (result.error) throw result.error
+} finally {
+  await sandbox.kill()
+}
 ```
 
-### `Sandbox.connect(sandboxId, opts?)`
-
-Connect to an existing sandbox by ID. Throws `NotFoundError` if it has been killed or has expired.
-
-### `Sandbox.list(opts?)`
-
-List all running sandboxes for the authenticated account.
-
----
-
-### Account and provisioning
-
-| Namespace | Methods |
-|---|---|
-| `lizard.workspaces` | `list()`, `create({ name })`, `delete(id, { force? })`, `find(nameOrSlugOrId)` |
-| `lizard.apiKeys` | `list()`, `create({ name, workspaces?, projects? })`, `delete(id)` |
-| `lizard.projects` | `list({ workspaceId? })`, `get(id)`, `create({ workspaceId, name })`, `update(id, { name })`, `delete(id)` |
-| `lizard.regions` | `list()` |
-| `lizard.billing` | `balance()`, `transactions({ limit?, cursor?, includeUsage? })`, `summary()`, `live()` — **unscoped keys only** |
-| `lizard.whoami()` | The account behind the credential; a scoped key gets identity and its own scopes, not the account's email or balance |
-| `lizard.platform` | The raw HTTP client, for endpoints not wrapped yet |
-
-`workspaces.delete()` is empty-only by default; the server refuses while any project, sandbox or volume remains. `{ force: true }` deletes the workspace and everything in it, irreversibly.
-
-In Python the namespaces are `lizard.workspaces`, `lizard.api_keys`, `lizard.regions`, `lizard.billing`, and arguments are snake_case (`workspace_id`, `include_usage`).
-
-### Volumes
-
-| Method | Description |
-|---|---|
-| `lizard.volumes.getOrCreate(name, { sizeGb?, region? })` | The volume with this name, created if absent |
-| `lizard.volumes.create(name, { sizeGb?, region? })` | Create; throws `ConflictError` if the name is taken |
-| `lizard.volumes.get(nameOrId)` | Look one up |
-| `lizard.volumes.list()` | Every volume in the client's project |
-| `lizard.volumes.delete(nameOrId)` | Delete |
-
-A volume's **name** is its key inside a project, so an agent can reconstruct it between runs without storing an id. The static `Volume.*` forms take an explicit `projectId` as their first argument.
-
-`region` places the volume (see `lizard.regions.list()` for valid ids) and, because a volume is node-local, also fixes the region of any sandbox that mounts it. You normally set it here or nowhere.
+## Configuration
 
----
+The SDK reads `LIZARD_API_KEY` and, optionally, `LIZARD_API_URL` (default: `https://lizard.build`). You can also pass `apiKey` and `apiUrl` to the constructor or static sandbox methods.
 
-### `sandbox.fs`
+Pass `timeoutMs` to `create()` to set the sandbox lifetime. The default is five minutes. `timeoutMs` on `process.exec()` or `runCode()` controls that call, not the sandbox lifetime.
 
-Read and write files inside the sandbox filesystem.
+## Runtime limits
 
-| Method | Description |
-|---|---|
-| `fs.write(path, data)` | Write a file (string or bytes) |
-| `fs.read(path)` | Read a file as a string |
-| `fs.list(path)` | List directory contents |
-| `fs.remove(path)` | Delete a file or directory |
-| `fs.makeDir(path)` | Create a directory and parents |
+Sandboxes run on Kubernetes. Use volumes mounted at `/workspace` to keep files after a sandbox ends. Pause, resume, fork, snapshot creation and snapshot restore return HTTP 501 on the current backend.
 
-### `sandbox.process`
-
-Execute commands inside the sandbox.
-
-| Method | Description |
-|---|---|
-| `process.exec(cmd, opts?)` | Run a command and wait for it to finish |
-
-`exec` returns `{ stdout, stderr, exitCode }` (JS) or `ProcessResult` (Python). In Python the method is named `exec_` because `exec` is a reserved keyword.
-
-### `sandbox.getHost(port)`
-
-Returns a public HTTPS URL for a port listening inside the sandbox — no tunneling required.
-
-```ts
-await sandbox.process.exec('npx -y serve -p 3000 &')
-const url = await sandbox.getHost(3000)
-// https://{sandboxId}-3000.sandbox.{region}.onlizard.com
-```
-
-### `sandbox.pause()` / `sandbox.resume()`
-
-**Not implemented** for the current runtime — both always fail with HTTP 501. Use a [volume](#persisting-work-across-sandboxes) to carry work across sandboxes.
-
-### `sandbox.kill()`
-
-Terminate the sandbox and release all resources.
-
-### `sandbox.setTimeout(ms)`
-
-Extend or reduce the sandbox timeout.
-
----
-
-## Environment Variables
-
-| Variable | Description |
-|---|---|
-| `LIZARD_API_KEY` | API key (required — get one at [lizard.build](https://lizard.build)) |
-| `LIZARD_API_URL` | Override the API base URL (default: `https://lizard.build`) |
-
-The `X-API-Key` header is used for all authenticated requests.
-
-## Deploy What You Build
-
-Once your agent has produced a working app inside a sandbox, deploy it as a persistent Lizard service — no Dockerfile needed:
-
-```bash
-lizard up
-```
+`getHost()` returns a hostname without `https://`. File writes accept UTF-8 text or valid UTF-8 bytes; `readBytes()` supports binary downloads.
 
-Lizard manages the sandbox runtime.
+## Learn more
 
-## License
+- [Sandbox reference](https://github.com/lizard-build/lizard-sdk/blob/main/docs/sandboxes.md)
+- [Platform guide](https://github.com/lizard-build/lizard-sdk/blob/main/docs/platform.md)
+- [CLI coverage and migration](https://github.com/lizard-build/lizard-sdk/blob/main/docs/cli-parity.md)
+- [Source and issues](https://github.com/lizard-build/lizard-sdk)
 
-Apache-2.0
+[Apache-2.0](https://github.com/lizard-build/lizard-sdk/blob/main/LICENSE)

package/dist/index.d.mts

@@ -114,7 +114,7 @@ declare class AddonsAPI {
         memoryMb?: number;
         storageGb?: number;
     }): Promise<Addon>;
-    /** Restart an addon VM. */
+    /** Restart an addon. */
     redeploy(projectId: string, addonId: string): Promise<void>;
     rename(projectId: string, addonId: string, name: string): Promise<unknown>;
     secrets(projectId: string, addonId: string): Promise<Array<{
@@ -395,7 +395,7 @@ interface ProcessInfo {
 /** Signals accepted by {@link Process.kill}. */
 type ProcessSignal = 'SIGTERM' | 'SIGKILL' | 'SIGINT' | 'SIGHUP' | 'SIGQUIT' | 'SIGUSR1' | 'SIGUSR2';
 /**
- * The result of a process execution inside a Lizard microVM.
+ * The result of a process execution inside a Lizard sandbox.
  */
 interface ProcessResult {
     stdout: string;
@@ -418,7 +418,7 @@ interface ProcessOpts {
     onPid?: (pid: number) => void;
 }
 /**
- * Runs processes inside a Lizard sandbox microVM.
+ * Runs processes inside a Lizard sandbox.
  *
  * Access via `sandbox.process`.
  */
@@ -427,12 +427,12 @@ declare class Process {
     private readonly config;
     constructor(sandboxId: string, config: ConnectionConfig);
     /**
-     * Execute a command inside the microVM and wait for it to complete.
+     * Execute a command inside the sandbox and wait for it to complete.
      *
      * The command runs in a shell inside the Lizard sandbox and returns
      * stdout, stderr, and the exit code when it finishes.
      *
-     * @param cmd Shell command to run inside the microVM.
+     * @param cmd Shell command to run inside the sandbox.
      * @param opts Optional execution options — environment variables, working
      *   directory, user, and timeout.
      *
@@ -511,7 +511,7 @@ interface FileInfo {
     modTime?: number;
 }
 /**
- * Read and write files inside a Lizard sandbox microVM.
+ * Read and write files inside a Lizard sandbox.
  *
  * Access via `sandbox.fs`.
  */
@@ -520,23 +520,24 @@ declare class Fs {
     private readonly config;
     constructor(sandboxId: string, config: ConnectionConfig);
     /**
-     * Write a file into the microVM filesystem.
+     * Write a file into the sandbox filesystem.
      *
      * Creates parent directories automatically if they don't exist.
+     * Byte input must contain valid UTF-8; arbitrary binary uploads are unsupported.
      *
      * @example
      * ```ts
      * await sandbox.fs.write('/app/index.js', 'console.log("hello")')
      * ```
      *
-     * @example Write binary data:
+     * @example Write UTF-8 bytes:
      * ```ts
-     * await sandbox.fs.write('/app/data.bin', buffer)
+     * await sandbox.fs.write('/app/notes.txt', new TextEncoder().encode('hello'))
      * ```
      */
     write(path: string, data: string | Uint8Array, opts?: FsOpts): Promise<void>;
     /**
-     * Read a file from the microVM filesystem.
+     * Read a file from the sandbox filesystem.
      *
      * @returns The file contents as a UTF-8 string.
      *
@@ -546,22 +547,23 @@ declare class Fs {
      * ```
      */
     read(path: string, opts?: FsOpts): Promise<string>;
+    /** Read a file as bytes. */
+    readBytes(path: string, opts?: FsOpts): Promise<Uint8Array>;
     /**
-     * List files and directories at the given path inside the microVM.
+     * List files and directories at the given path inside the sandbox.
      *
      * @example
      * ```ts
      * const entries = await sandbox.fs.list('/app')
      * ```
      */
-    readBytes(path: string, opts?: FsOpts): Promise<Uint8Array>;
     list(path: string, opts?: FsOpts): Promise<FileInfo[]>;
     /**
-     * Remove a file or directory from the microVM filesystem.
+     * Remove a file or directory from the sandbox filesystem.
      */
     remove(path: string, opts?: FsOpts): Promise<void>;
     /**
-     * Create a directory (and any missing parents) inside the microVM.
+     * Create a directory (and any missing parents) inside the sandbox.
      */
     makeDir(path: string, opts?: FsOpts): Promise<void>;
     /**
@@ -730,10 +732,9 @@ declare class SandboxClient {
 }
 
 /**
- * A Lizard sandbox — an isolated Linux environment that starts in under a second.
+ * A Linux sandbox running on Kubernetes.
  *
- * Each sandbox is a full Linux environment with its own filesystem, network, and
- * process namespace, restored from a pre-warmed template snapshot.
+ * Run commands, read and write files, and expose HTTP ports in a sandbox.
  *
  * Sandboxes are **ephemeral**: killing one, or letting it hit its timeout, discards
  * everything written inside it. State that has to outlive a sandbox belongs on a
@@ -745,10 +746,14 @@ declare class SandboxClient {
  * import { Sandbox } from '@lizard-build/sdk'
  *
  * const sandbox = await Sandbox.create('base', { project: 'my-project' })
- * await sandbox.fs.write('/app/index.js', 'console.log("hello world")')
- * const result = await sandbox.process.exec('node /app/index.js')
- * console.log(result.stdout) // "hello world"
- * await sandbox.kill()
+ * try {
+ *   await sandbox.fs.write('/tmp/hello.txt', 'hello world')
+ *   const result = await sandbox.process.exec('cat /tmp/hello.txt')
+ *   if (result.exitCode !== 0) throw new Error(result.stderr)
+ *   console.log(result.stdout)
+ * } finally {
+ *   await sandbox.kill()
+ * }
  * ```
  *
  * @example Carry work across sandboxes with a volume:
@@ -769,11 +774,11 @@ declare class Sandbox extends SandboxClient {
     protected static readonly defaultTemplate: string;
     protected static readonly defaultTimeoutMs: number;
     /**
-     * Unique identifier of this sandbox microVM.
+     * Unique identifier of this sandbox.
      */
     readonly sandboxId: string;
     /**
-     * Read and write files inside the microVM filesystem.
+     * Read and write files inside the sandbox filesystem.
      *
      * @example
      * ```ts
@@ -783,7 +788,7 @@ declare class Sandbox extends SandboxClient {
      */
     readonly fs: Fs;
     /**
-     * Execute processes inside the microVM.
+     * Execute processes inside the sandbox.
      *
      * @example
      * ```ts
@@ -807,16 +812,15 @@ declare class Sandbox extends SandboxClient {
     /**
      * Create a new Lizard sandbox from the specified template.
      *
-     * Available templates: `base` (Debian + Node.js 26) and `code-interpreter-v1`
-     * (Python 3.14 + Node.js 26). Custom templates can be built and pushed via
-     * `lizard push`.
+     * Template availability and installed tools depend on the platform and region.
+     * Use `base` for shell commands or `CodeSandbox` for stateful code execution.
      *
      * @param template Name of the sandbox template to boot from.
      *
      * @example
      * ```ts
      * const sandbox = await Sandbox.create('base', { project: 'my-project' })
-     * const sandbox = await Sandbox.create('code-interpreter-v1', { project: 'my-project', timeoutMs: 10 * 60 * 1000 })
+     * const pythonSandbox = await Sandbox.create('code-interpreter-v1', { project: 'my-project', timeoutMs: 10 * 60 * 1000 })
      * ```
      */
     static create(template: string, opts?: SandboxOpts): Promise<Sandbox>;
@@ -826,11 +830,7 @@ declare class Sandbox extends SandboxClient {
      * Verifies the sandbox exists and is reachable, then returns a handle to it.
      * Throws `NotFoundError` if it has been killed or has expired.
      *
-     * This used to call `resume` first, on the assumption that a sandbox you are
-     * reconnecting to might be paused. Sandboxes are pods now and pause/resume is a
-     * `501` on every one of them, so that call turned every `connect()` into an
-     * error against a perfectly healthy sandbox. Connecting does not need to change
-     * a sandbox's state, so it no longer tries to.
+     * Connecting reads sandbox metadata without changing its state.
      *
      * @example
      * ```ts
@@ -852,25 +852,21 @@ declare class Sandbox extends SandboxClient {
     /**
      * Kill the sandbox and release its resources immediately.
      *
-     * @returns `true` if the microVM was terminated, `false` if it was already gone.
+     * @returns `true` if the sandbox was terminated, `false` if it was already gone.
      */
     kill(opts?: ConnectionOpts): Promise<boolean>;
     /**
-     * Pause the sandbox by freezing it in place.
+     * Request sandbox pause. The Kubernetes backend returns HTTP 501.
      *
-     * @deprecated Not implemented for the current runtime — always throws
-     * `LizardError` with HTTP 501. Sandboxes run as pods, and the equivalent is a CRIU
-     * checkpoint of the pod, which is not built. To park work across a gap, put it on a
-     * {@link Volume} and create a fresh sandbox on that volume later; the volume is the
-     * part that is meant to outlive a sandbox.
+     * @deprecated Unsupported on Kubernetes. Save files to a {@link Volume}
+     * and attach it to a new sandbox instead.
      */
     pause(opts?: ConnectionOpts): Promise<boolean>;
     /**
-     * Resume a paused sandbox.
+     * Request sandbox resume. The Kubernetes backend returns HTTP 501.
      *
-     * @deprecated Not implemented for the current runtime — always throws
-     * `LizardError` with HTTP 501. See {@link pause}. `Sandbox.connect()` no longer
-     * calls this, so reconnecting to a running sandbox works without it.
+     * @deprecated Unsupported on Kubernetes. Use {@link Sandbox.connect} to
+     * reconnect to a running sandbox.
      */
     resume(opts?: ConnectionOpts): Promise<boolean>;
     /**
@@ -884,23 +880,25 @@ declare class Sandbox extends SandboxClient {
      */
     setTimeout(timeoutMs: number, opts?: ConnectionOpts): Promise<void>;
     /**
-     * Get the public HTTPS URL for a port exposed inside the sandbox.
+     * Register a public HTTPS route and return its hostname without a scheme.
      *
-     * Useful for accessing HTTP servers started inside the microVM from your
+     * Useful for accessing HTTP servers started inside the sandbox from your
      * agent or tests without additional tunneling.
      *
      * @example
      * ```ts
-     * await sandbox.process.exec('npx -y serve -p 3000 &')
-     * const url = sandbox.getHost(3000)
-     * // https://{sandboxId}-3000.sandbox.{region}.onlizard.com
+     * // Start an HTTP server on port 3000 before exposing it.
+     * const hostname = await sandbox.getHost(3000)
+     * console.log(`https://${hostname}`)
      * ```
      */
     getHost(port: number, opts?: ConnectionOpts): Promise<string>;
+    /** Fork is unsupported on Kubernetes; the backend returns HTTP 501. */
     fork(opts?: {
         count?: number;
         timeoutMs?: number;
     }): Promise<unknown>;
+    /** Snapshot creation is unsupported on Kubernetes; the backend returns HTTP 501. */
     snapshot(name?: string): Promise<unknown>;
     unexpose(port: number): Promise<void>;
     logs(opts?: {
@@ -908,6 +906,7 @@ declare class Sandbox extends SandboxClient {
         signal?: AbortSignal;
     }): AsyncGenerator<StreamEvent, any, any>;
     static snapshots(projectId: string, opts?: ConnectionOpts): Promise<unknown[]>;
+    /** Snapshot restore is unsupported on Kubernetes; the backend returns HTTP 501. */
     static restore(snapshotId: string, opts?: ConnectionOpts & {
         timeoutMs?: number;
     }): Promise<Sandbox>;
@@ -1602,7 +1601,7 @@ type OutputItem = {
     message: string;
     traceback: string;
 };
-/** Error thrown when executed code raises an exception. */
+/** Error returned in Execution.error when executed code raises an exception. */
 declare class ExecutionError extends Error {
     readonly name: string;
     readonly traceback: string;
@@ -1637,7 +1636,7 @@ interface RunCodeOpts {
     context?: CodeContext;
     /** Extra environment variables available to the code. */
     envs?: Record<string, string>;
-    /** Max time to wait for the code to finish, in ms. Default: 60_000. */
+    /** Client timeout in milliseconds. No client timer is set when omitted. */
     timeoutMs?: number;
     onStdout?: (data: string) => void;
     onStderr?: (data: string) => void;
@@ -1659,7 +1658,7 @@ interface CreateContextOpts {
  *
  * @example
  * ```ts
- * import { CodeSandbox } from 'lizard/code-interpreter'
+ * import { CodeSandbox } from '@lizard-build/sdk'
  *
  * const sandbox = await CodeSandbox.create({ project: 'my-project' })
  *
@@ -1690,8 +1689,7 @@ declare class CodeSandbox extends Sandbox {
      *
      * @returns Execution result with stdout, stderr, results, and any error.
      *
-     * @throws {ExecutionError} if you pass neither language nor context and no
-     *   default context exists — which cannot happen in normal usage.
+     * Code errors appear in `execution.error`; request failures throw.
      *
      * @example
      * ```ts