@lizard-build/sdk 0.1.20 → 0.1.21

package/README.md

@@ -19,10 +19,15 @@ pip install lizard-sdk
 ### JavaScript / TypeScript
 
 ```ts
-import { Sandbox } from '@lizard-build/sdk'
+import { Lizard } from '@lizard-build/sdk'
+
+// 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 microVM from the 'base' template (Debian + Node.js 20)
-const sandbox = await Sandbox.create('base')
+const sandbox = await lizard.create('base')
 
 // Write a file directly into the microVM filesystem
 await sandbox.fs.write('/app/server.js', `
@@ -44,10 +49,14 @@ await sandbox.kill()
 ### Python
 
 ```python
-from lizard import Sandbox
+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 microVM from the 'code-interpreter-v1' template
-sandbox = Sandbox.create("code-interpreter-v1")
+sandbox = lizard.create("code-interpreter-v1")
 
 # Write a script into the microVM filesystem
 sandbox.fs.write("/app/main.py", """
@@ -76,29 +85,28 @@ sandbox.kill()
 Sandboxes can be snapshotted mid-execution and resumed exactly where they left off — including installed packages, in-memory state, and running processes. This makes Lizard sandboxes well-suited for long-running AI agent workflows where you want to checkpoint and continue across separate invocations.
 
 ```ts
-// Boot and set up the environment once
-const sandbox = await Sandbox.create('code-interpreter-v1')
+// Boot and set up the environment once (reusing the `lizard` client from above)
+const sandbox = await lizard.create('code-interpreter-v1')
 await sandbox.process.exec('pip install numpy pandas scikit-learn')
 const id = sandbox.sandboxId
 await sandbox.pause()
 
 // Later — resume instantly from the snapshot (no reinstall needed)
-const resumed = await Sandbox.connect(id)
+const resumed = await lizard.connect(id)
 const result = await resumed.process.exec('python -c "import sklearn; print(sklearn.__version__)"')
 console.log(result.stdout)
 await resumed.kill()
 ```
 
 ```python
-from lizard import Sandbox
-
-sandbox = Sandbox.create("code-interpreter-v1")
+# reusing the `lizard` client from above
+sandbox = lizard.create("code-interpreter-v1")
 sandbox.process.exec_("pip install numpy pandas scikit-learn")
 sandbox_id = sandbox.sandbox_id
 sandbox.pause()
 
 # Resume later — environment is exactly as left
-resumed = Sandbox.connect(sandbox_id)
+resumed = lizard.connect(sandbox_id)
 result = resumed.process.exec_("python -c 'import sklearn; print(sklearn.__version__)'")
 print(result.stdout)
 resumed.kill()
@@ -106,13 +114,23 @@ resumed.kill()
 
 ## 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?)`
 
-Boot a new Lizard microVM. Built-in templates: `base` (Debian + Node.js 20) and `code-interpreter-v1` (Python 3.11 + Node.js 20). Custom templates can be pushed via `lizard push`.
+Boot a new Lizard microVM. Built-in templates: `base` (Debian + Node.js 20) and `code-interpreter-v1` (Python 3.11 + Node.js 20). Custom templates can be pushed via `lizard push`. 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.
 
 ```ts
-const sandbox = await Sandbox.create('base')
-const sandbox = await Sandbox.create('code-interpreter-v1', { timeoutMs: 10 * 60 * 1000 })
+const sandbox = await Sandbox.create('base', { project: 'my-project' })
+const sandbox = await Sandbox.create('code-interpreter-v1', { project: 'my-project', timeoutMs: 10 * 60 * 1000 })
 ```
 
 ### `Sandbox.connect(sandboxId, opts?)`

package/dist/index.d.mts

@@ -138,10 +138,14 @@ interface SandboxInfo {
 }
 interface SandboxOpts extends ConnectionOpts {
     /**
-     * ID of the project this sandbox belongs to. Required: a sandbox must be
-     * attributed to a project so its CPU, RAM, egress, and storage are billed.
+     * The project this sandbox belongs to — its ID, slug, or name. Required:
+     * a sandbox must be attributed to a project so its CPU, RAM, egress, and
+     * storage are billed. Prefer the {@link Lizard} client, which pins a project
+     * for you. Ignored when {@link SandboxOpts.projectId} is set.
      */
-    projectId: string;
+    project?: string;
+    /** Exact project ID — skips resolving {@link SandboxOpts.project}. */
+    projectId?: string;
     template?: string;
     metadata?: Record<string, string>;
     envs?: Record<string, string>;
@@ -180,7 +184,7 @@ declare class SandboxClient {
  * ```ts
  * import { Sandbox } from 'lizard'
  *
- * const sandbox = await Sandbox.create('base', { projectId: 'proj_abc123' })
+ * 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"
@@ -189,7 +193,7 @@ declare class SandboxClient {
  *
  * @example Pause and resume a long-running session:
  * ```ts
- * const sandbox = await Sandbox.create('code-interpreter-v1', { projectId: 'proj_abc123' })
+ * const sandbox = await Sandbox.create('code-interpreter-v1', { project: 'my-project' })
  * await sandbox.process.exec('pip install numpy')
  * const id = sandbox.sandboxId
  * await sandbox.pause()
@@ -234,7 +238,7 @@ declare class Sandbox extends SandboxClient {
      *
      * @example
      * ```ts
-     * const sandbox = await Sandbox.create({ projectId: 'proj_abc123' })
+     * const sandbox = await Sandbox.create({ project: 'my-project' })
      * ```
      */
     static create(opts?: SandboxOpts): Promise<Sandbox>;
@@ -249,8 +253,8 @@ declare class Sandbox extends SandboxClient {
      *
      * @example
      * ```ts
-     * const sandbox = await Sandbox.create('base', { projectId: 'proj_abc123' })
-     * const sandbox = await Sandbox.create('code-interpreter-v1', { projectId: 'proj_abc123', timeoutMs: 10 * 60 * 1000 })
+     * const sandbox = await Sandbox.create('base', { project: 'my-project' })
+     * const sandbox = await Sandbox.create('code-interpreter-v1', { project: 'my-project', timeoutMs: 10 * 60 * 1000 })
      * ```
      */
     static create(template: string, opts?: SandboxOpts): Promise<Sandbox>;
@@ -323,6 +327,63 @@ declare class Sandbox extends SandboxClient {
     private resolveOpts;
 }
 
+interface LizardOpts extends ConnectionOpts {
+    /**
+     * The project every sandbox created through this client belongs to — its ID,
+     * slug, or name. Required: sandboxes are billed per project, so a project-less
+     * sandbox cannot be created.
+     */
+    project: string;
+}
+/**
+ * The Lizard client — the entry point for creating sandboxes.
+ *
+ * A client is pinned to one project (billing is metered per project), so every
+ * sandbox it creates is attributed correctly. The project reference — ID, slug,
+ * or name — is resolved to a project ID on first use and cached.
+ *
+ * @example
+ * ```ts
+ * import { Lizard } from '@lizard-build/sdk'
+ *
+ * const lizard = new Lizard({ project: 'my-project' }) // apiKey from LIZARD_API_KEY
+ *
+ * const sandbox = await lizard.create('base')
+ * await sandbox.process.exec('echo hello')
+ * await sandbox.kill()
+ * ```
+ */
+declare class Lizard {
+    private readonly config;
+    private readonly projectRef;
+    constructor(opts: LizardOpts);
+    /** Resolve the client's project reference to a stable project ID (cached). */
+    projectId(): Promise<string>;
+    private connectionOpts;
+    /**
+     * Create a new sandbox in this client's project.
+     *
+     * @example
+     * ```ts
+     * const sandbox = await lizard.create('base')
+     * const sandbox = await lizard.create('code-interpreter-v1', { timeoutMs: 600_000 })
+     * ```
+     */
+    create(template?: string, opts?: Omit<SandboxOpts, 'project' | 'projectId'>): Promise<Sandbox>;
+    /** Connect to an existing sandbox by ID (resumes it if paused). */
+    connect(sandboxId: string, opts?: ConnectionOpts): Promise<Sandbox>;
+    /** List running sandboxes for the authenticated account. */
+    list(opts?: ConnectionOpts): Promise<SandboxInfo[]>;
+}
+
+/**
+ * Resolve a project reference — its ID, slug, or name — to the stable project
+ * ID the API bills against. Exact-ID refs skip the network entirely.
+ *
+ * @throws {LizardError} when the reference matches no project the key can see.
+ */
+declare function resolveProjectId(ref: string, config: ConnectionConfig): Promise<string>;
+
 declare class LizardError extends Error {
     constructor(message: string);
 }
@@ -414,7 +475,7 @@ interface CreateContextOpts {
  * ```ts
  * import { CodeSandbox } from 'lizard/code-interpreter'
  *
- * const sandbox = await CodeSandbox.create({ projectId: 'proj_abc123' })
+ * const sandbox = await CodeSandbox.create({ project: 'my-project' })
  *
  * await sandbox.runCode('x = 42')
  * const result = await sandbox.runCode('print(x * 2)')
@@ -517,4 +578,4 @@ declare class Volume {
     delete(projectId: string): Promise<void>;
 }
 
-export { AuthenticationError, type CodeContext, CodeSandbox, type ConnectionOpts, type CreateContextOpts, type CreateVolumeOpts, Execution, ExecutionError, type FileInfo, type FsOpts, LizardError, NotFoundError, type ProcessOpts, type ProcessResult, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, TimeoutError, Volume, type VolumeInfo };
+export { AuthenticationError, type CodeContext, CodeSandbox, type ConnectionOpts, type CreateContextOpts, type CreateVolumeOpts, Execution, ExecutionError, type FileInfo, type FsOpts, Lizard, LizardError, type LizardOpts, NotFoundError, type ProcessOpts, type ProcessResult, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, TimeoutError, Volume, type VolumeInfo, resolveProjectId };

package/dist/index.d.ts

@@ -138,10 +138,14 @@ interface SandboxInfo {
 }
 interface SandboxOpts extends ConnectionOpts {
     /**
-     * ID of the project this sandbox belongs to. Required: a sandbox must be
-     * attributed to a project so its CPU, RAM, egress, and storage are billed.
+     * The project this sandbox belongs to — its ID, slug, or name. Required:
+     * a sandbox must be attributed to a project so its CPU, RAM, egress, and
+     * storage are billed. Prefer the {@link Lizard} client, which pins a project
+     * for you. Ignored when {@link SandboxOpts.projectId} is set.
      */
-    projectId: string;
+    project?: string;
+    /** Exact project ID — skips resolving {@link SandboxOpts.project}. */
+    projectId?: string;
     template?: string;
     metadata?: Record<string, string>;
     envs?: Record<string, string>;
@@ -180,7 +184,7 @@ declare class SandboxClient {
  * ```ts
  * import { Sandbox } from 'lizard'
  *
- * const sandbox = await Sandbox.create('base', { projectId: 'proj_abc123' })
+ * 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"
@@ -189,7 +193,7 @@ declare class SandboxClient {
  *
  * @example Pause and resume a long-running session:
  * ```ts
- * const sandbox = await Sandbox.create('code-interpreter-v1', { projectId: 'proj_abc123' })
+ * const sandbox = await Sandbox.create('code-interpreter-v1', { project: 'my-project' })
  * await sandbox.process.exec('pip install numpy')
  * const id = sandbox.sandboxId
  * await sandbox.pause()
@@ -234,7 +238,7 @@ declare class Sandbox extends SandboxClient {
      *
      * @example
      * ```ts
-     * const sandbox = await Sandbox.create({ projectId: 'proj_abc123' })
+     * const sandbox = await Sandbox.create({ project: 'my-project' })
      * ```
      */
     static create(opts?: SandboxOpts): Promise<Sandbox>;
@@ -249,8 +253,8 @@ declare class Sandbox extends SandboxClient {
      *
      * @example
      * ```ts
-     * const sandbox = await Sandbox.create('base', { projectId: 'proj_abc123' })
-     * const sandbox = await Sandbox.create('code-interpreter-v1', { projectId: 'proj_abc123', timeoutMs: 10 * 60 * 1000 })
+     * const sandbox = await Sandbox.create('base', { project: 'my-project' })
+     * const sandbox = await Sandbox.create('code-interpreter-v1', { project: 'my-project', timeoutMs: 10 * 60 * 1000 })
      * ```
      */
     static create(template: string, opts?: SandboxOpts): Promise<Sandbox>;
@@ -323,6 +327,63 @@ declare class Sandbox extends SandboxClient {
     private resolveOpts;
 }
 
+interface LizardOpts extends ConnectionOpts {
+    /**
+     * The project every sandbox created through this client belongs to — its ID,
+     * slug, or name. Required: sandboxes are billed per project, so a project-less
+     * sandbox cannot be created.
+     */
+    project: string;
+}
+/**
+ * The Lizard client — the entry point for creating sandboxes.
+ *
+ * A client is pinned to one project (billing is metered per project), so every
+ * sandbox it creates is attributed correctly. The project reference — ID, slug,
+ * or name — is resolved to a project ID on first use and cached.
+ *
+ * @example
+ * ```ts
+ * import { Lizard } from '@lizard-build/sdk'
+ *
+ * const lizard = new Lizard({ project: 'my-project' }) // apiKey from LIZARD_API_KEY
+ *
+ * const sandbox = await lizard.create('base')
+ * await sandbox.process.exec('echo hello')
+ * await sandbox.kill()
+ * ```
+ */
+declare class Lizard {
+    private readonly config;
+    private readonly projectRef;
+    constructor(opts: LizardOpts);
+    /** Resolve the client's project reference to a stable project ID (cached). */
+    projectId(): Promise<string>;
+    private connectionOpts;
+    /**
+     * Create a new sandbox in this client's project.
+     *
+     * @example
+     * ```ts
+     * const sandbox = await lizard.create('base')
+     * const sandbox = await lizard.create('code-interpreter-v1', { timeoutMs: 600_000 })
+     * ```
+     */
+    create(template?: string, opts?: Omit<SandboxOpts, 'project' | 'projectId'>): Promise<Sandbox>;
+    /** Connect to an existing sandbox by ID (resumes it if paused). */
+    connect(sandboxId: string, opts?: ConnectionOpts): Promise<Sandbox>;
+    /** List running sandboxes for the authenticated account. */
+    list(opts?: ConnectionOpts): Promise<SandboxInfo[]>;
+}
+
+/**
+ * Resolve a project reference — its ID, slug, or name — to the stable project
+ * ID the API bills against. Exact-ID refs skip the network entirely.
+ *
+ * @throws {LizardError} when the reference matches no project the key can see.
+ */
+declare function resolveProjectId(ref: string, config: ConnectionConfig): Promise<string>;
+
 declare class LizardError extends Error {
     constructor(message: string);
 }
@@ -414,7 +475,7 @@ interface CreateContextOpts {
  * ```ts
  * import { CodeSandbox } from 'lizard/code-interpreter'
  *
- * const sandbox = await CodeSandbox.create({ projectId: 'proj_abc123' })
+ * const sandbox = await CodeSandbox.create({ project: 'my-project' })
  *
  * await sandbox.runCode('x = 42')
  * const result = await sandbox.runCode('print(x * 2)')
@@ -517,4 +578,4 @@ declare class Volume {
     delete(projectId: string): Promise<void>;
 }
 
-export { AuthenticationError, type CodeContext, CodeSandbox, type ConnectionOpts, type CreateContextOpts, type CreateVolumeOpts, Execution, ExecutionError, type FileInfo, type FsOpts, LizardError, NotFoundError, type ProcessOpts, type ProcessResult, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, TimeoutError, Volume, type VolumeInfo };
+export { AuthenticationError, type CodeContext, CodeSandbox, type ConnectionOpts, type CreateContextOpts, type CreateVolumeOpts, Execution, ExecutionError, type FileInfo, type FsOpts, Lizard, LizardError, type LizardOpts, NotFoundError, type ProcessOpts, type ProcessResult, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, TimeoutError, Volume, type VolumeInfo, resolveProjectId };

package/dist/index.js

@@ -22,11 +22,13 @@ var index_exports = {};
 __export(index_exports, {
   AuthenticationError: () => AuthenticationError,
   CodeSandbox: () => CodeSandbox,
+  Lizard: () => Lizard,
   LizardError: () => LizardError,
   NotFoundError: () => NotFoundError,
   Sandbox: () => Sandbox,
   TimeoutError: () => TimeoutError,
-  Volume: () => Volume
+  Volume: () => Volume,
+  resolveProjectId: () => resolveProjectId
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -91,6 +93,36 @@ async function handleApiError(res) {
   throw new LizardError(`API error ${res.status}: ${message}`);
 }
 
+// src/project.ts
+var projectIdCache = /* @__PURE__ */ new Map();
+async function resolveProjectId(ref, config) {
+  const cacheKey = `${config.apiUrl}\0${ref}`;
+  const cached = projectIdCache.get(cacheKey);
+  if (cached) return cached;
+  const res = await fetch(`${config.apiUrl}/api/projects`, { headers: config.headers });
+  if (!res.ok) await handleApiError(res);
+  const projects = await res.json();
+  const lower = ref.toLowerCase();
+  const match = projects.find(
+    (p) => p.id.toLowerCase() === lower || p.slug?.toLowerCase() === lower || p.name?.toLowerCase() === lower
+  );
+  if (!match) {
+    const available = projects.map((p) => p.slug || p.id).join(", ") || "(none)";
+    throw new LizardError(
+      `Project "${ref}" not found. Available: ${available}. Pass the project's ID, slug, or name.`
+    );
+  }
+  projectIdCache.set(cacheKey, match.id);
+  return match.id;
+}
+function requireProjectRef(opts) {
+  if (opts?.projectId) return { projectId: opts.projectId };
+  if (opts?.project) return { project: opts.project };
+  throw new LizardError(
+    'A project is required to create a sandbox. Pass `project` (its ID, slug, or name), or create sandboxes through a Lizard client: new Lizard({ project: "my-project" }).'
+  );
+}
+
 // src/sandbox/process.ts
 var Process = class {
   constructor(sandboxId, config) {
@@ -233,19 +265,16 @@ var Fs = class {
 // src/sandbox/client.ts
 var SandboxClient = class {
   static async createSandbox(template, timeoutMs, opts) {
-    if (!opts?.projectId) {
-      throw new LizardError(
-        "projectId is required: a sandbox must belong to a project so its usage is billed. Pass { projectId } to Sandbox.create()."
-      );
-    }
+    const ref = requireProjectRef(opts);
     const config = new ConnectionConfig(opts);
+    const projectId = ref.projectId ?? await resolveProjectId(ref.project, config);
     const res = await fetch(`${config.apiUrl}/api/sandboxes`, {
       method: "POST",
       headers: config.headers,
       body: JSON.stringify({
-        projectId: opts.projectId,
         template,
         timeoutMs,
+        projectId,
         metadata: opts?.metadata,
         envs: opts?.envs,
         volumeId: opts?.volumeId
@@ -427,6 +456,48 @@ var Sandbox = class extends SandboxClient {
 Sandbox.defaultTemplate = "base";
 Sandbox.defaultTimeoutMs = DEFAULT_SANDBOX_TIMEOUT_MS;
 
+// src/lizard.ts
+var Lizard = class {
+  constructor(opts) {
+    if (!opts?.project) {
+      throw new LizardError(
+        'A project is required. Pass project (its ID, slug, or name): new Lizard({ project: "my-project" }).'
+      );
+    }
+    this.config = new ConnectionConfig(opts);
+    this.projectRef = opts.project;
+  }
+  /** Resolve the client's project reference to a stable project ID (cached). */
+  async projectId() {
+    return resolveProjectId(this.projectRef, this.config);
+  }
+  async connectionOpts(extra) {
+    return { apiKey: this.config.apiKey, apiUrl: this.config.apiUrl, ...extra };
+  }
+  /**
+   * Create a new sandbox in this client's project.
+   *
+   * @example
+   * ```ts
+   * const sandbox = await lizard.create('base')
+   * const sandbox = await lizard.create('code-interpreter-v1', { timeoutMs: 600_000 })
+   * ```
+   */
+  async create(template, opts) {
+    const projectId = await this.projectId();
+    const sandboxOpts = { ...opts, ...await this.connectionOpts(), projectId };
+    return template ? Sandbox.create(template, sandboxOpts) : Sandbox.create(sandboxOpts);
+  }
+  /** Connect to an existing sandbox by ID (resumes it if paused). */
+  async connect(sandboxId, opts) {
+    return Sandbox.connect(sandboxId, await this.connectionOpts(opts));
+  }
+  /** List running sandboxes for the authenticated account. */
+  async list(opts) {
+    return Sandbox.list(await this.connectionOpts(opts));
+  }
+};
+
 // src/code-interpreter/types.ts
 var ExecutionError = class extends Error {
   constructor(name, message, traceback) {
@@ -669,9 +740,11 @@ var Volume = class _Volume {
 0 && (module.exports = {
   AuthenticationError,
   CodeSandbox,
+  Lizard,
   LizardError,
   NotFoundError,
   Sandbox,
   TimeoutError,
-  Volume
+  Volume,
+  resolveProjectId
 });

package/dist/index.mjs

@@ -59,6 +59,36 @@ async function handleApiError(res) {
   throw new LizardError(`API error ${res.status}: ${message}`);
 }
 
+// src/project.ts
+var projectIdCache = /* @__PURE__ */ new Map();
+async function resolveProjectId(ref, config) {
+  const cacheKey = `${config.apiUrl}\0${ref}`;
+  const cached = projectIdCache.get(cacheKey);
+  if (cached) return cached;
+  const res = await fetch(`${config.apiUrl}/api/projects`, { headers: config.headers });
+  if (!res.ok) await handleApiError(res);
+  const projects = await res.json();
+  const lower = ref.toLowerCase();
+  const match = projects.find(
+    (p) => p.id.toLowerCase() === lower || p.slug?.toLowerCase() === lower || p.name?.toLowerCase() === lower
+  );
+  if (!match) {
+    const available = projects.map((p) => p.slug || p.id).join(", ") || "(none)";
+    throw new LizardError(
+      `Project "${ref}" not found. Available: ${available}. Pass the project's ID, slug, or name.`
+    );
+  }
+  projectIdCache.set(cacheKey, match.id);
+  return match.id;
+}
+function requireProjectRef(opts) {
+  if (opts?.projectId) return { projectId: opts.projectId };
+  if (opts?.project) return { project: opts.project };
+  throw new LizardError(
+    'A project is required to create a sandbox. Pass `project` (its ID, slug, or name), or create sandboxes through a Lizard client: new Lizard({ project: "my-project" }).'
+  );
+}
+
 // src/sandbox/process.ts
 var Process = class {
   constructor(sandboxId, config) {
@@ -201,19 +231,16 @@ var Fs = class {
 // src/sandbox/client.ts
 var SandboxClient = class {
   static async createSandbox(template, timeoutMs, opts) {
-    if (!opts?.projectId) {
-      throw new LizardError(
-        "projectId is required: a sandbox must belong to a project so its usage is billed. Pass { projectId } to Sandbox.create()."
-      );
-    }
+    const ref = requireProjectRef(opts);
     const config = new ConnectionConfig(opts);
+    const projectId = ref.projectId ?? await resolveProjectId(ref.project, config);
     const res = await fetch(`${config.apiUrl}/api/sandboxes`, {
       method: "POST",
       headers: config.headers,
       body: JSON.stringify({
-        projectId: opts.projectId,
         template,
         timeoutMs,
+        projectId,
         metadata: opts?.metadata,
         envs: opts?.envs,
         volumeId: opts?.volumeId
@@ -395,6 +422,48 @@ var Sandbox = class extends SandboxClient {
 Sandbox.defaultTemplate = "base";
 Sandbox.defaultTimeoutMs = DEFAULT_SANDBOX_TIMEOUT_MS;
 
+// src/lizard.ts
+var Lizard = class {
+  constructor(opts) {
+    if (!opts?.project) {
+      throw new LizardError(
+        'A project is required. Pass project (its ID, slug, or name): new Lizard({ project: "my-project" }).'
+      );
+    }
+    this.config = new ConnectionConfig(opts);
+    this.projectRef = opts.project;
+  }
+  /** Resolve the client's project reference to a stable project ID (cached). */
+  async projectId() {
+    return resolveProjectId(this.projectRef, this.config);
+  }
+  async connectionOpts(extra) {
+    return { apiKey: this.config.apiKey, apiUrl: this.config.apiUrl, ...extra };
+  }
+  /**
+   * Create a new sandbox in this client's project.
+   *
+   * @example
+   * ```ts
+   * const sandbox = await lizard.create('base')
+   * const sandbox = await lizard.create('code-interpreter-v1', { timeoutMs: 600_000 })
+   * ```
+   */
+  async create(template, opts) {
+    const projectId = await this.projectId();
+    const sandboxOpts = { ...opts, ...await this.connectionOpts(), projectId };
+    return template ? Sandbox.create(template, sandboxOpts) : Sandbox.create(sandboxOpts);
+  }
+  /** Connect to an existing sandbox by ID (resumes it if paused). */
+  async connect(sandboxId, opts) {
+    return Sandbox.connect(sandboxId, await this.connectionOpts(opts));
+  }
+  /** List running sandboxes for the authenticated account. */
+  async list(opts) {
+    return Sandbox.list(await this.connectionOpts(opts));
+  }
+};
+
 // src/code-interpreter/types.ts
 var ExecutionError = class extends Error {
   constructor(name, message, traceback) {
@@ -636,9 +705,11 @@ var Volume = class _Volume {
 export {
   AuthenticationError,
   CodeSandbox,
+  Lizard,
   LizardError,
   NotFoundError,
   Sandbox,
   TimeoutError,
-  Volume
+  Volume,
+  resolveProjectId
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lizard-build/sdk",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "Lizard SDK — cloud sandboxes for AI agents",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",