@lizard-build/sdk 0.1.77 → 0.1.79

package/README.md

@@ -1,6 +1,15 @@
-# Lizard SDK for TypeScript
+# Lizard SDK for TypeScript and JavaScript
 
-Run commands, work with files and execute code in Linux sandboxes that run as Firecracker microVMs. The SDK also manages Lizard apps, databases, storage and projects.
+Lizard (lizard.build) provides cloud sandboxes for AI agents and code execution. Lizard SDK is the official TypeScript and JavaScript client for creating and controlling Lizard Sandboxes.
+
+Run AI-generated Python in a stateful code interpreter, execute shell commands, read and write files, or control a browser and desktop. Each sandbox runs as a Firecracker microVM with its own kernel.
+
+## Use cases
+
+- Execute AI-generated code with a [stateful Python code interpreter](https://lizard.build/docs/sandboxes/code-interpreter/).
+- Run coding agents such as [Claude Code](https://lizard.build/docs/sandboxes/guides/claude-code/) in a cloud sandbox.
+- Automate a browser or desktop with [screenshots, clicks and keyboard input](https://github.com/lizard-build/lizard-sdk/blob/main/docs/sandboxes.md#desktop-computer-use).
+- Open an agent's dev server through a [private preview URL](https://lizard.build/docs/sandboxes/preview-urls/).
 
 ## Install
 
@@ -10,7 +19,7 @@ Requires Node.js 18+.
 npm install @lizard-build/sdk
 ```
 
-Create an API key and project at [lizard.build](https://lizard.build), then set:
+Start with Lizard Pro or its trial; see [billing and trial terms](https://lizard.build/docs/platform/billing/). Create an API key and project at [lizard.build](https://lizard.build), then set:
 
 ```sh
 export LIZARD_API_KEY="your-api-key"
@@ -38,17 +47,50 @@ try {
 
 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.
 
-## Machine size
+## Run code with state (CodeSandbox)
+
+`CodeSandbox` boots the `interpreter` template and runs Python in a persistent Jupyter kernel inside the sandbox: variables survive between calls, the value of the last expression and matplotlib charts come back in `results`, and exceptions in `error`.
+
+```ts
+import { CodeSandbox } from '@lizard-build/sdk'
+
+const sandbox = await CodeSandbox.create({ project: 'my-project', timeoutMs: 300_000 })
+try {
+  const setup = await sandbox.runCode('x = 21')
+  if (setup.error) throw setup.error
+  const run = await sandbox.runCode('x * 2')
+  if (run.error) throw run.error
+  const out = run.results[0]
+  if (out?.type === 'result') console.log(out.data) // "42"
+} finally {
+  await sandbox.kill()
+}
+```
+
+`language: 'bash'` and `language: 'javascript'` (the `interpreter` template ships Node 22) run each call as a fresh process with no shared state. See the [code interpreter guide](https://lizard.build/docs/sandboxes/code-interpreter/).
+
+## Account, pricing and machine size
+
+Lizard Pro costs $19 a month, taxes included, with $19 of usage each month. Unused usage does not carry over. Usage above that amount is pay as you go at the published rates. New accounts can start a 7-day trial with $5 of usage; a card is required, and nothing is charged until the trial ends. If trial usage runs out, workloads pause until Pro starts. See the current [billing and trial terms](https://lizard.build/docs/platform/billing/).
+
+Sandbox rates below were checked on October 23, 2026. See [current sizes and prices](https://lizard.build/docs/platform/limits/#sandbox-sizes) before estimating costs.
 
 Sandboxes come in three sizes: `small` (2 vCPU / 4 GB, $0.0162/h), `medium` (4 vCPU / 8 GB, $0.0324/h, the default) and `large` (8 vCPU / 16 GB, $0.0648/h). Billing is flat by size, per second while the sandbox runs, including idle time. CPU and RAM are included. The sandbox egress allowance is [2 TB per account over a rolling 30 days](https://lizard.build/docs/platform/limits/#sandbox-egress), with no separate per-GB charge. A successful pause stops compute charges; storage in Persistent Volumes is billed separately, including while paused.
 
 ```ts
 const sandbox = await lizard.create('base', { size: 'large' })
+try {
+  const result = await sandbox.process.exec("python -c 'print(2 ** 10)'")
+  if (result.exitCode !== 0) throw new Error(result.stderr)
+  console.log(result.stdout)
+} finally {
+  await sandbox.kill()
+}
 ```
 
 ## Stream command output
 
-Inside the `try` block above:
+Inside the `try` block in the first sandbox example:
 
 ```ts
 const result = await sandbox.process.exec('printf "hello\\n"', {
@@ -67,55 +109,40 @@ The `desktop` template runs an Openbox desktop with Chromium, streamed to a brow
 import { Sandbox } from '@lizard-build/sdk'
 
 const sandbox = await Sandbox.create('desktop', { project: 'my-project' })
-const { url, viewOnlyUrl } = await sandbox.desktop.start() // open `url` in a browser
-await sandbox.desktop.openUrl('https://example.com')
-await sandbox.desktop.click(640, 400)
-await sandbox.desktop.type('hello')
-await sandbox.desktop.press('Return')
-const png: Uint8Array = await sandbox.desktop.screenshot()
-```
-
-Treat `url` like a credential: anyone with it can see and control the desktop. Share `viewOnlyUrl` when someone only needs to watch. See the [desktop guide](../../docs/sandboxes.md#desktop-computer-use).
-
-## Run Python
-
-Run Python with the `interpreter` template. Each process command starts a separate Python process, so Python variables do not survive between calls; use `CodeSandbox` (below) when they should.
-
-```ts
-import { Sandbox } from '@lizard-build/sdk';
-
-const sandbox = await Sandbox.create('interpreter', {
-  projectId: 'proj_123', timeoutMs: 300_000,
-});
 try {
-  const result = await sandbox.process.exec("python -c 'print(2 ** 10)'");
-  console.log(result.stdout, result.stderr, result.exitCode);
+  const { url, viewOnlyUrl } = await sandbox.desktop.start() // open `url` in a browser
+  await sandbox.desktop.openUrl('https://example.com')
+  await sandbox.desktop.click(640, 400)
+  await sandbox.desktop.type('hello')
+  await sandbox.desktop.press('Return')
+  const png: Uint8Array = await sandbox.desktop.screenshot()
 } finally {
-  await sandbox.kill();
+  await sandbox.kill()
 }
 ```
 
-To run code snippets with state carried between calls, use `CodeSandbox` (`runCode` / `run_code`): it boots the `interpreter` template and runs Python in a persistent Jupyter kernel inside the sandbox. See [Run code](https://github.com/lizard-build/lizard-sdk/blob/main/docs/sandboxes.md#run-code-codesandbox).
+Treat `url` like a credential: anyone with it can see and control the desktop. Share `viewOnlyUrl` when someone only needs to watch. See the [desktop guide](https://github.com/lizard-build/lizard-sdk/blob/main/docs/sandboxes.md#desktop-computer-use).
 
-## Run code with state (CodeSandbox)
+## Run Python
 
-`CodeSandbox` boots the `interpreter` template and runs Python in a persistent Jupyter kernel inside the sandbox: variables survive between calls, the value of the last expression and matplotlib charts come back in `results`, and exceptions in `error`.
+Run Python with the `interpreter` template. Each process command starts a separate Python process, so Python variables do not survive between calls; use `CodeSandbox` when they should.
 
 ```ts
-import { CodeSandbox } from '@lizard-build/sdk';
+import { Sandbox } from '@lizard-build/sdk'
 
-const sandbox = await CodeSandbox.create({ projectId: 'proj_123' });
+const sandbox = await Sandbox.create('interpreter', {
+  project: 'my-project', timeoutMs: 300_000,
+})
 try {
-  await sandbox.runCode('x = 21');
-  const run = await sandbox.runCode('x * 2');
-  const out = run.results[0];
-  if (out?.type === 'result') console.log(out.data); // "42"
+  const result = await sandbox.process.exec("python -c 'print(2 ** 10)'")
+  if (result.exitCode !== 0) throw new Error(result.stderr)
+  console.log(result.stdout, result.stderr, result.exitCode)
 } finally {
-  await sandbox.kill();
+  await sandbox.kill()
 }
 ```
 
-`language: 'bash'` and `language: 'javascript'` (the `interpreter` template ships Node 22) run each call as a fresh process with no shared state.
+To keep state between calls, use `CodeSandbox.runCode()`. See the [code execution reference](https://github.com/lizard-build/lizard-sdk/blob/main/docs/sandboxes.md#run-code-codesandbox).
 
 ## Configuration
 
@@ -127,18 +154,25 @@ Pass `timeoutMs` to `create()` to set the sandbox lifetime. The default is five
 
 ## Runtime limits
 
-Lizard Sandboxes run as Firecracker microVMs, each with its own kernel. Use volumes mounted at `/workspace` to keep files after a sandbox ends. `pause()`/`resume()` keep memory and running processes; `snapshot()` is ready in about 2 s and `Sandbox.restore()` starts a copy in about 0.4 s; `fork()` clones a running sandbox. File watching and sandbox log streaming are not available yet. Volumes can grow but not shrink, and a sandbox with a volume attached cannot be forked. See the [snapshot guide](../../docs/sandboxes.md#pause-resume-snapshots-and-fork).
+Lizard Sandboxes run as Firecracker microVMs, each with its own kernel. Use Persistent Volumes mounted at `/workspace` to keep files after a sandbox ends. `pause()`/`resume()` keep memory and running processes; `snapshot()` is ready in about 2 s and `Sandbox.restore()` starts a copy in about 0.4 s; `fork()` clones a running sandbox. File watching and sandbox log streaming are not available yet. Volumes can grow but not shrink, and a sandbox with a volume attached cannot be forked. See the [snapshot guide](https://github.com/lizard-build/lizard-sdk/blob/main/docs/sandboxes.md#pause-resume-snapshots-and-fork).
 
 `getHost()` returns a hostname without `https://`; the port is private, so send `sandbox.accessToken` as the `X-Lizard-Access-Token` header (or use `exposePort()`, which also returns a browser `url` carrying the token). File writes accept text or bytes (binary is sent exactly); `readBytes()` supports binary downloads.
 
 ## Current command and lifetime limits
 
-Command results contain stdout, stderr, and the exit code. Command timeouts are limited to 1–600 seconds. The command options `envs`, `workdir` and `user` apply to that command; create-time `envs` apply to every command, and create-time `metadata` is returned by `getInfo()` / `get_info()`.
+Command results contain stdout, stderr, and the exit code. Command timeouts are limited to 1–600 seconds. The command options `envs`, `workdir` and `user` apply to that command; create-time `envs` apply to every command, and create-time `metadata` is returned by `getInfo()`.
+
+The SDK and CLI default to a five-minute lifetime. The raw API and dashboard default to no expiration. Set an explicit lifetime: `timeoutMs: 0` at creation disables expiration; a positive value sets a deadline. `setTimeout()` accepts 1000–2147483647 ms, not zero. Commands do not reset the deadline. This is not an idle timer.
+
+## Other SDK capabilities
 
-The SDK and CLI default to a five-minute lifetime. The raw API and dashboard default to no expiration. Set an explicit lifetime: `timeoutMs: 0` at creation disables expiration; a positive value sets a deadline. `setTimeout` accepts 1000–2147483647 ms, not zero. Commands do not reset the deadline. This is not an idle timer.
+The SDK also manages apps, Managed Postgres, Managed Redis, Managed Object Storage and projects. See the [platform guide](https://github.com/lizard-build/lizard-sdk/blob/main/docs/platform.md).
 
 ## Learn more
 
+- [Sandboxes overview and current limits](https://lizard.build/docs/sandboxes/)
+- [Sandboxes quickstart](https://lizard.build/docs/sandboxes/quickstart/)
+- [Billing and trial terms](https://lizard.build/docs/platform/billing/)
 - [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)

package/dist/index.d.mts

@@ -895,13 +895,11 @@ declare class GitReposAPI {
         name: string;
     }>;
     get(repo: RepoRef): Promise<RepoMeta>;
-    /** `apiCommits`: also accept commits written through the API (`commitFiles`, `land`); new repositories take pushes only. */
     update(repo: RepoRef, opts: {
         name?: string;
         description?: string;
         private?: boolean;
         defaultBranch?: string;
-        apiCommits?: boolean;
     }): Promise<{
         ok: boolean;
     }>;
@@ -952,9 +950,10 @@ declare class GitReposAPI {
     }>;
     compare(repo: RepoRef, base: string, head: string): Promise<unknown>;
     /**
-     * Commit files on the server: no clone, no push. Only on a repository whose admin allowed
-     * it (`update(repo, { apiCommits: true })`); new repositories take changes by git push only
-     * (403 otherwise). Answers 409 when `expect` no longer matches.
+     * Commit files on the server: no clone, no push (every commit to Lizard Git is made this
+     * way). With `expect` (the commit your change was made against), a branch that moved since
+     * is the server's to resolve: other files go on the new tip, the same files are merged line
+     * by line, and only a real conflict answers 409 with the paths.
      */
     commitFiles(repo: RepoRef, opts: CommitFilesOpts): Promise<{
         sha: string;
@@ -974,9 +973,9 @@ declare class GitReposAPI {
     reflog(repo: RepoRef, ref?: string): Promise<unknown[]>;
     archive(repo: RepoRef, ref: string, format?: 'zip' | 'tar.gz'): Promise<Uint8Array>;
     /**
-     * The HTTPS clone URL. With `withKey`, it carries the API key, so plain `git clone` works
-     * without a helper; git then keeps it in .git/config. For anything shared or logged, use a
-     * limited Lizard Git token (`tokens.create`) as `apiKey` instead of the account's key.
+     * @deprecated Lizard Git no longer serves the git protocol (contents are kept as changesets,
+     * files by hash): this address answers 410. Read with `tree`/`file`/`raw`/`archive`, write
+     * with `commitFiles`, and check out with the Lizard CLI (`lizard git clone`).
      */
     cloneUrl(repo: RepoRef, opts?: {
         withKey?: boolean;

package/dist/index.d.ts

@@ -895,13 +895,11 @@ declare class GitReposAPI {
         name: string;
     }>;
     get(repo: RepoRef): Promise<RepoMeta>;
-    /** `apiCommits`: also accept commits written through the API (`commitFiles`, `land`); new repositories take pushes only. */
     update(repo: RepoRef, opts: {
         name?: string;
         description?: string;
         private?: boolean;
         defaultBranch?: string;
-        apiCommits?: boolean;
     }): Promise<{
         ok: boolean;
     }>;
@@ -952,9 +950,10 @@ declare class GitReposAPI {
     }>;
     compare(repo: RepoRef, base: string, head: string): Promise<unknown>;
     /**
-     * Commit files on the server: no clone, no push. Only on a repository whose admin allowed
-     * it (`update(repo, { apiCommits: true })`); new repositories take changes by git push only
-     * (403 otherwise). Answers 409 when `expect` no longer matches.
+     * Commit files on the server: no clone, no push (every commit to Lizard Git is made this
+     * way). With `expect` (the commit your change was made against), a branch that moved since
+     * is the server's to resolve: other files go on the new tip, the same files are merged line
+     * by line, and only a real conflict answers 409 with the paths.
      */
     commitFiles(repo: RepoRef, opts: CommitFilesOpts): Promise<{
         sha: string;
@@ -974,9 +973,9 @@ declare class GitReposAPI {
     reflog(repo: RepoRef, ref?: string): Promise<unknown[]>;
     archive(repo: RepoRef, ref: string, format?: 'zip' | 'tar.gz'): Promise<Uint8Array>;
     /**
-     * The HTTPS clone URL. With `withKey`, it carries the API key, so plain `git clone` works
-     * without a helper; git then keeps it in .git/config. For anything shared or logged, use a
-     * limited Lizard Git token (`tokens.create`) as `apiKey` instead of the account's key.
+     * @deprecated Lizard Git no longer serves the git protocol (contents are kept as changesets,
+     * files by hash): this address answers 410. Read with `tree`/`file`/`raw`/`archive`, write
+     * with `commitFiles`, and check out with the Lizard CLI (`lizard git clone`).
      */
     cloneUrl(repo: RepoRef, opts?: {
         withKey?: boolean;

package/dist/index.js

@@ -632,7 +632,6 @@ var GitReposAPI = class {
   get(repo) {
     return this.c.get(repoPath(repo));
   }
-  /** `apiCommits`: also accept commits written through the API (`commitFiles`, `land`); new repositories take pushes only. */
   update(repo, opts) {
     return this.c.patch(repoPath(repo), opts);
   }
@@ -692,9 +691,10 @@ var GitReposAPI = class {
     return this.c.get(qs(`${repoPath(repo)}/compare`, { base, head }));
   }
   /**
-   * Commit files on the server: no clone, no push. Only on a repository whose admin allowed
-   * it (`update(repo, { apiCommits: true })`); new repositories take changes by git push only
-   * (403 otherwise). Answers 409 when `expect` no longer matches.
+   * Commit files on the server: no clone, no push (every commit to Lizard Git is made this
+   * way). With `expect` (the commit your change was made against), a branch that moved since
+   * is the server's to resolve: other files go on the new tip, the same files are merged line
+   * by line, and only a real conflict answers 409 with the paths.
    */
   commitFiles(repo, opts) {
     const { idempotencyKey, ...body } = opts;
@@ -712,9 +712,9 @@ var GitReposAPI = class {
     return this.c.bytes(`${repoPath(repo)}/archive/${seg(ref)}.${format}`);
   }
   /**
-   * The HTTPS clone URL. With `withKey`, it carries the API key, so plain `git clone` works
-   * without a helper; git then keeps it in .git/config. For anything shared or logged, use a
-   * limited Lizard Git token (`tokens.create`) as `apiKey` instead of the account's key.
+   * @deprecated Lizard Git no longer serves the git protocol (contents are kept as changesets,
+   * files by hash): this address answers 410. Read with `tree`/`file`/`raw`/`archive`, write
+   * with `commitFiles`, and check out with the Lizard CLI (`lizard git clone`).
    */
   cloneUrl(repo, opts = {}) {
     repoPath(repo);

package/dist/index.mjs

@@ -560,7 +560,6 @@ var GitReposAPI = class {
   get(repo) {
     return this.c.get(repoPath(repo));
   }
-  /** `apiCommits`: also accept commits written through the API (`commitFiles`, `land`); new repositories take pushes only. */
   update(repo, opts) {
     return this.c.patch(repoPath(repo), opts);
   }
@@ -620,9 +619,10 @@ var GitReposAPI = class {
     return this.c.get(qs(`${repoPath(repo)}/compare`, { base, head }));
   }
   /**
-   * Commit files on the server: no clone, no push. Only on a repository whose admin allowed
-   * it (`update(repo, { apiCommits: true })`); new repositories take changes by git push only
-   * (403 otherwise). Answers 409 when `expect` no longer matches.
+   * Commit files on the server: no clone, no push (every commit to Lizard Git is made this
+   * way). With `expect` (the commit your change was made against), a branch that moved since
+   * is the server's to resolve: other files go on the new tip, the same files are merged line
+   * by line, and only a real conflict answers 409 with the paths.
    */
   commitFiles(repo, opts) {
     const { idempotencyKey, ...body } = opts;
@@ -640,9 +640,9 @@ var GitReposAPI = class {
     return this.c.bytes(`${repoPath(repo)}/archive/${seg(ref)}.${format}`);
   }
   /**
-   * The HTTPS clone URL. With `withKey`, it carries the API key, so plain `git clone` works
-   * without a helper; git then keeps it in .git/config. For anything shared or logged, use a
-   * limited Lizard Git token (`tokens.create`) as `apiKey` instead of the account's key.
+   * @deprecated Lizard Git no longer serves the git protocol (contents are kept as changesets,
+   * files by hash): this address answers 410. Read with `tree`/`file`/`raw`/`archive`, write
+   * with `commitFiles`, and check out with the Lizard CLI (`lizard git clone`).
    */
   cloneUrl(repo, opts = {}) {
     repoPath(repo);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lizard-build/sdk",
-  "version": "0.1.77",
-  "description": "TypeScript SDK for Lizard: Firecracker microVM sandboxes, code execution and cloud apps.",
+  "version": "0.1.79",
+  "description": "TypeScript and JavaScript SDK for Lizard (lizard.build): cloud sandboxes for AI agents and code execution.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -41,6 +41,9 @@
     "directory": "packages/js"
   },
   "homepage": "https://lizard.build",
+  "bugs": {
+    "url": "https://github.com/lizard-build/lizard-sdk/issues"
+  },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "tsup": "^8.0.0",