@lizard-build/sdk 0.1.22 → 0.1.24

package/README.md

@@ -2,7 +2,7 @@
 
 Firecracker microVM sandboxes for AI agents — boot a full Linux environment in milliseconds, run code, write files, and expose ports, all from your agent or CI pipeline.
 
-Each sandbox is an isolated microVM with its own filesystem, network, and process namespace. Sandboxes can be snapshotted and resumed instantly, so long-running agent sessions survive restarts without re-running setup.
+Each sandbox is an isolated microVM with its own filesystem, network, and process namespace. Sandboxes can be paused — vCPUs frozen, memory and running processes kept — and resumed instantly, so a long-running agent session picks up without re-running setup.
 
 ## Install
 
@@ -26,7 +26,7 @@ import { Lizard } from '@lizard-build/sdk'
 // 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)
+// Boot a microVM from the 'base' template (Debian + Node.js 26)
 const sandbox = await lizard.create('base')
 
 // Write a file directly into the microVM filesystem
@@ -82,7 +82,9 @@ sandbox.kill()
 
 ## Pause and Resume
 
-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.
+Sandboxes can be paused mid-execution and resumed exactly where they left off — including installed packages, in-memory state, and running processes. Pausing freezes the microVM's vCPUs; memory and processes stay in the host's RAM and are not written to disk, so a paused sandbox does not survive a host failure. This makes Lizard sandboxes well-suited for long-running AI agent workflows where you want to stop and continue across separate invocations.
+
+Pausing does not stop the sandbox timeout — a paused sandbox is still deleted at its original expiry (default 5 minutes). Pass `timeoutMs: 0` (`timeout_ms=0` in Python) at create time to opt out of expiry.
 
 ```ts
 // Boot and set up the environment once (reusing the `lizard` client from above)
@@ -91,7 +93,7 @@ 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)
+// Later — resume instantly (no reinstall needed)
 const resumed = await lizard.connect(id)
 const result = await resumed.process.exec('python -c "import sklearn; print(sklearn.__version__)"')
 console.log(result.stdout)
@@ -126,7 +128,7 @@ const sandbox = await lizard.create('code-interpreter-v1', { timeoutMs: 10 * 60
 
 ### `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`. 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.
+Boot a new Lizard microVM. Built-in templates: `base` (Debian + Node.js 26) and `code-interpreter-v1` (Python 3.14 + Node.js 26). 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', { project: 'my-project' })
@@ -135,7 +137,7 @@ const sandbox = await Sandbox.create('code-interpreter-v1', { project: 'my-proje
 
 ### `Sandbox.connect(sandboxId, opts?)`
 
-Connect to an existing sandbox by ID. If the sandbox is paused, it is automatically resumed from its last snapshot.
+Connect to an existing sandbox by ID. If the sandbox is paused, it is automatically resumed.
 
 ### `Sandbox.list(opts?)`
 
@@ -177,7 +179,7 @@ const url = sandbox.getHost(3000)
 
 ### `sandbox.pause()` / `sandbox.resume()`
 
-Snapshot and restore the microVM state. Useful for checkpointing long agent sessions.
+Freeze and unfreeze the microVM's vCPUs. Memory and running processes are kept in the host's RAM, not written to disk. The timeout keeps running while paused.
 
 ### `sandbox.kill()`
 

package/dist/index.d.mts

@@ -177,12 +177,13 @@ declare class SandboxClient {
  *
  * Each sandbox is a full Linux environment with its own filesystem, network,
  * and process namespace. Sandboxes are spun up from templates and can be
- * paused to a snapshot, then resumed instantly — perfect for stateful AI
- * agent sessions or ephemeral code execution.
+ * paused — vCPUs frozen, memory and running processes kept — then resumed
+ * instantly, perfect for stateful AI agent sessions or ephemeral code
+ * execution.
  *
  * @example Basic usage:
  * ```ts
- * import { Sandbox } from 'lizard'
+ * 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")')
@@ -245,8 +246,8 @@ declare class Sandbox extends SandboxClient {
     /**
      * Create a new Lizard sandbox from the specified template.
      *
-     * Available templates: `base` (Debian + Node.js 20) and `code-interpreter-v1`
-     * (Python 3.11 + Node.js 20). Custom templates can be built and pushed via
+     * 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`.
      *
      * @param template Name of the sandbox template to boot from.
@@ -262,7 +263,7 @@ declare class Sandbox extends SandboxClient {
      * Connect to an existing sandbox by its ID.
      *
      * If the sandbox is currently paused, it will be automatically resumed
-     * from its last snapshot before this call returns.
+     * before this call returns.
      *
      * @example
      * ```ts
@@ -286,16 +287,21 @@ declare class Sandbox extends SandboxClient {
      */
     kill(opts?: ConnectionOpts): Promise<boolean>;
     /**
-     * Snapshot and pause the sandbox microVM.
+     * Pause the sandbox microVM by freezing its vCPUs.
      *
-     * The sandbox state — memory, filesystem, and running processes — is saved
-     * to a snapshot. Resume with `sandbox.resume()` or `Sandbox.connect(id)`.
+     * Memory, filesystem, and running processes are held in the host's RAM —
+     * nothing is written to disk, so a paused sandbox does not survive a host
+     * failure. Resume with `sandbox.resume()` or `Sandbox.connect(id)`.
+     *
+     * Pausing does not stop the timeout: a paused sandbox is still deleted at
+     * its original expiry (default 5 minutes). Pass `timeoutMs: 0` at create
+     * time to opt out of expiry.
      *
      * @returns `true` if paused successfully.
      */
     pause(opts?: ConnectionOpts): Promise<boolean>;
     /**
-     * Resume a paused sandbox from its last snapshot.
+     * Resume a paused sandbox by unfreezing its vCPUs.
      *
      * @returns `true` if resumed successfully.
      */
@@ -327,47 +333,428 @@ declare class Sandbox extends SandboxClient {
     private resolveOpts;
 }
 
+/** Shared HTTP helper for platform (non-sandbox) API calls. */
+declare class PlatformClient {
+    readonly config: ConnectionConfig;
+    constructor(opts: ConnectionOpts);
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body: unknown): Promise<T>;
+    delete<T = void>(path: string, body?: unknown): Promise<T>;
+    postForm<T>(path: string, form: FormData): Promise<T>;
+    /** Stream SSE events from a path, calling handler for each data line. */
+    streamSse(path: string): AsyncGenerator<string>;
+}
+
+interface Project {
+    id: string;
+    name: string;
+    slug: string;
+    workspaceId: string;
+    createdAt?: string;
+}
+interface CreateProjectOpts {
+    workspaceId: string;
+    name: string;
+}
+declare class ProjectsAPI {
+    private readonly client;
+    constructor(client: PlatformClient);
+    /** List all projects the API key can access. */
+    list(opts?: {
+        workspaceId?: string;
+    }): Promise<Project[]>;
+    /** Get a project by ID. */
+    get(id: string): Promise<Project>;
+    /** Create a new project. */
+    create(opts: CreateProjectOpts): Promise<Project>;
+    /** Update a project's name. */
+    update(id: string, opts: {
+        name?: string;
+    }): Promise<Project>;
+    /** Delete a project. */
+    delete(id: string): Promise<void>;
+}
+
+interface Service {
+    id: string;
+    name: string;
+    projectId: string;
+    status: 'none' | 'running' | 'crashed' | 'stopped';
+    deployStatus: 'idle' | 'building' | 'deploying' | 'restarting' | 'failed' | 'deleting';
+    domain?: string;
+    region?: string;
+    sourceType?: 'github' | 'upload';
+    repoUrl?: string;
+    branch?: string;
+    startCommand?: string;
+    buildCommand?: string;
+    containerPort?: number;
+}
+interface CreateServiceOpts {
+    projectId: string;
+    name: string;
+    sourceType?: 'github' | 'upload';
+    repoUrl?: string;
+    branch?: string;
+    startCommand?: string;
+    buildCommand?: string;
+    containerPort?: number;
+    region?: string;
+    /** Set to 0 for worker mode (no HTTP listener). */
+    port?: number;
+}
+interface ScaleOpts {
+    replicas?: number;
+    cpuMillis?: number;
+    memoryMi?: number;
+    storageMi?: number;
+}
+interface LogLine {
+    level: 'info' | 'error' | 'warn' | 'debug';
+    message: string;
+    ts: number;
+    service?: string;
+    replica?: string;
+}
+interface DeployEvent {
+    event: 'log' | 'done' | 'error' | 'deployed' | 'failed' | 'deploying';
+    line?: string;
+    message?: string;
+    status?: string;
+    url?: string | null;
+}
+/**
+ * Handle for a running deploy — stream its logs or await completion.
+ *
+ * @example
+ * ```ts
+ * const deploy = await lizard.services.upload({ projectId, source: fs.readFileSync('app.tar.gz') })
+ * for await (const line of deploy.logs()) console.log(line)
+ * const result = await deploy.wait()
+ * console.log('deployed to', result.url)
+ * ```
+ */
+declare class DeployHandle {
+    private readonly _serviceId;
+    private readonly _buildId;
+    private readonly _client;
+    constructor(client: PlatformClient, serviceId: string, buildId?: string);
+    get serviceId(): string;
+    /** Stream build + runtime log lines until the deploy finishes. */
+    logs(): AsyncGenerator<string>;
+    /**
+     * Poll until the deploy reaches a terminal state.
+     * @returns `{ url, status }` on success; throws `LizardError` on failure.
+     */
+    wait(opts?: {
+        timeoutMs?: number;
+        pollMs?: number;
+    }): Promise<{
+        url: string | null;
+        status: string;
+    }>;
+}
+declare class ServicesAPI {
+    private readonly client;
+    constructor(client: PlatformClient);
+    /** List all services in a project. */
+    list(opts: {
+        projectId: string;
+    }): Promise<Service[]>;
+    /** Get a service by ID. */
+    get(id: string): Promise<Service>;
+    /**
+     * Create a service and start a deploy from a git repo.
+     * Returns a DeployHandle to track progress.
+     */
+    deploy(opts: CreateServiceOpts & {
+        waitForDeploy?: boolean;
+    }): Promise<DeployHandle>;
+    /**
+     * Upload a tarball and deploy it.
+     *
+     * @param opts.source - A `Buffer`, `Blob`, or `Uint8Array` of a `.tar.gz` file.
+     */
+    upload(opts: {
+        projectId: string;
+        name: string;
+        source: Blob | string;
+        startCommand?: string;
+        buildCommand?: string;
+        port?: number;
+        region?: string;
+    }): Promise<DeployHandle>;
+    /** Trigger a redeploy (rebuild from current source). */
+    redeploy(id: string): Promise<DeployHandle>;
+    /** Restart a service without rebuilding. */
+    restart(id: string): Promise<void>;
+    /** Scale a service. */
+    scale(id: string, opts: ScaleOpts): Promise<void>;
+    /**
+     * Get recent log lines. For a live tail, use the WebSocket API instead.
+     *
+     * @param opts.limit - Max lines to return (default 200, max 1000).
+     */
+    logs(id: string, opts?: {
+        limit?: number;
+        since?: string;
+    }): Promise<LogLine[]>;
+    /** Execute a command inside the running service VM. */
+    exec(id: string, cmd: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+    /** Update service configuration. */
+    update(id: string, opts: Partial<Pick<Service, 'name' | 'startCommand' | 'buildCommand' | 'containerPort' | 'repoUrl' | 'branch' | 'sourceType'>>): Promise<Service>;
+    /** Delete a service. */
+    delete(id: string): Promise<void>;
+}
+
+type AddonType = 'postgres' | 'mysql' | 'mongodb' | 'redis' | 's3';
+interface Addon {
+    id: string;
+    name: string;
+    type: AddonType;
+    projectId: string;
+    status: 'none' | 'running' | 'crashed' | 'stopped';
+    deployStatus: string;
+    version?: string;
+    /** Exposed connection variables (e.g. DATABASE_URL, REDIS_URL). */
+    env?: Record<string, string>;
+}
+interface CreateAddonOpts {
+    projectId: string;
+    type: AddonType;
+    name?: string;
+    version?: string;
+    /** vCPU count */
+    vcpu?: number;
+    /** Memory in MB */
+    memoryMb?: number;
+    /** Storage in GB */
+    storageGb?: number;
+}
+declare class AddonsAPI {
+    private readonly client;
+    constructor(client: PlatformClient);
+    /** List all addons in a project. */
+    list(opts: {
+        projectId: string;
+    }): Promise<Addon[]>;
+    /** Get an addon by ID. */
+    get(projectId: string, addonId: string): Promise<Addon>;
+    /**
+     * Create a new managed addon (database, cache, or object store).
+     *
+     * @example
+     * ```ts
+     * const pg = await lizard.addons.create({ projectId, type: 'postgres' })
+     * // Inject into a service:
+     * await lizard.secrets.set({ serviceId: svcId, key: 'DATABASE_URL', value: `${{${pg.name}.DATABASE_URL}}` })
+     * ```
+     */
+    create(opts: CreateAddonOpts): Promise<Addon>;
+    /** Delete an addon. */
+    delete(projectId: string, addonId: string): Promise<void>;
+    /** Resize an addon (CPU / memory / storage). */
+    resize(projectId: string, addonId: string, opts: {
+        vcpu?: number;
+        memoryMb?: number;
+        storageGb?: number;
+    }): Promise<Addon>;
+    /** Restart an addon VM. */
+    redeploy(projectId: string, addonId: string): Promise<void>;
+}
+
+interface Secret {
+    key: string;
+    value: string;
+}
+interface SetSecretOpts {
+    key: string;
+    value: string;
+    /** Target a specific service. Omit for project-scope. */
+    serviceId?: string;
+    /** If true, set at project scope (shared across all services). */
+    global?: boolean;
+}
+interface ListSecretsOpts {
+    serviceId?: string;
+}
+declare class SecretsAPI {
+    private readonly client;
+    constructor(client: PlatformClient);
+    /**
+     * List secrets for a project or service.
+     *
+     * @param projectId - The project ID.
+     * @param opts.serviceId - If given, list service-scoped secrets instead of project secrets.
+     */
+    list(projectId: string, opts?: ListSecretsOpts): Promise<Secret[]>;
+    /**
+     * Set one or more secrets.
+     *
+     * ```ts
+     * // Service-scoped secret (default):
+     * await lizard.secrets.set(projectId, { key: 'DATABASE_URL', value: '${{postgres.DATABASE_URL}}', serviceId })
+     *
+     * // Project-scoped (shared across all services):
+     * await lizard.secrets.set(projectId, { key: 'LOG_LEVEL', value: 'info', global: true })
+     * ```
+     */
+    set(projectId: string, secrets: SetSecretOpts | SetSecretOpts[]): Promise<void>;
+    /** Delete a secret by key. */
+    delete(projectId: string, opts: {
+        key: string;
+        serviceId?: string;
+    }): Promise<void>;
+}
+
+interface DomainInfo {
+    domain: string;
+    /** 'pending' until DNS propagates and the platform verifies the CNAME/TXT record. */
+    verified: boolean;
+    txtRecord?: string;
+    cnameTarget?: string;
+}
+declare class DomainsAPI {
+    private readonly client;
+    constructor(client: PlatformClient);
+    /**
+     * Show the current domain(s) for a service.
+     * The platform-assigned `.onlizard.com` subdomain is always present.
+     */
+    list(serviceId: string): Promise<DomainInfo[]>;
+    /**
+     * Attach a custom domain to a service.
+     * Returns the DNS records to add before calling `verify()`.
+     *
+     * @example
+     * ```ts
+     * const info = await lizard.domains.add(serviceId, 'api.example.com')
+     * console.log('Add CNAME:', info.cnameTarget)
+     * ```
+     */
+    add(serviceId: string, domain: string): Promise<DomainInfo>;
+    /**
+     * Verify that DNS records have propagated and activate the domain.
+     * Call after adding the CNAME or TXT record returned by `add()`.
+     */
+    verify(serviceId: string, domain: string): Promise<DomainInfo>;
+}
+
+type MetricRange = '1h' | '6h' | '24h' | '7d' | '14d' | '30d';
+interface MetricPoint {
+    t: number;
+    value: number;
+}
+interface ServiceMetrics {
+    cpu: MetricPoint[];
+    memory: MetricPoint[];
+    networkRx: MetricPoint[];
+    networkTx: MetricPoint[];
+    diskRead: MetricPoint[];
+    diskWrite: MetricPoint[];
+}
+interface CostMetrics {
+    compute: number;
+    egress: number;
+    storage: number;
+    total: number;
+    currency: string;
+}
+declare class MetricsAPI {
+    private readonly client;
+    constructor(client: PlatformClient);
+    /** Get CPU metrics for a service or addon. */
+    cpu(id: string, range?: MetricRange): Promise<MetricPoint[]>;
+    /** Get memory metrics for a service or addon. */
+    memory(id: string, range?: MetricRange): Promise<MetricPoint[]>;
+    /** Get network I/O metrics for a service. */
+    network(id: string, range?: MetricRange): Promise<{
+        rx: MetricPoint[];
+        tx: MetricPoint[];
+    }>;
+    /** Get disk I/O metrics for a service. */
+    disk(id: string, range?: MetricRange): Promise<{
+        read: MetricPoint[];
+        write: MetricPoint[];
+    }>;
+    /**
+     * Get cost breakdown for a project over the given range.
+     * Costs are in USD cents unless the `currency` field says otherwise.
+     */
+    cost(projectId: string, range?: MetricRange): Promise<CostMetrics>;
+    /**
+     * Convenience: fetch all metric types for a service in one call.
+     */
+    all(id: string, range?: MetricRange): Promise<ServiceMetrics>;
+}
+
 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.
+     * slug, or name. Required for sandbox operations; optional for platform
+     * management (projects, services, addons, etc.).
      */
-    project: string;
+    project?: string;
 }
 /**
- * The Lizard client — the entry point for creating sandboxes.
+ * The Lizard client — entry point for sandboxes and platform management.
  *
- * 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
+ * @example Sandbox usage (backward-compatible)
  * ```ts
- * import { Lizard } from '@lizard-build/sdk'
- *
- * const lizard = new Lizard({ project: 'my-project' }) // apiKey from LIZARD_API_KEY
- *
+ * const lizard = new Lizard({ project: 'my-project' })
  * const sandbox = await lizard.create('base')
  * await sandbox.process.exec('echo hello')
  * await sandbox.kill()
  * ```
+ *
+ * @example Platform management
+ * ```ts
+ * const lizard = new Lizard({ apiKey: process.env.LIZARD_API_KEY })
+ *
+ * // Deploy from git
+ * const deploy = await lizard.services.deploy({ projectId, name: 'api', repoUrl: '...', branch: 'main' })
+ * const result = await deploy.wait()
+ * console.log('Deployed to', result.url)
+ *
+ * // Add a Postgres addon and wire it to the service
+ * const pg = await lizard.addons.create({ projectId, type: 'postgres' })
+ * await lizard.secrets.set(projectId, {
+ *   serviceId: result.serviceId,
+ *   key: 'DATABASE_URL',
+ *   value: `${{${pg.name}.DATABASE_URL}}`,
+ * })
+ * ```
  */
 declare class Lizard {
     private readonly config;
     private readonly projectRef;
+    private _platform;
+    /** Manage projects. */
+    readonly projects: ProjectsAPI;
+    /** Deploy and manage services. */
+    readonly services: ServicesAPI;
+    /** Manage addons (postgres, redis, s3, mysql, mongodb). */
+    readonly addons: AddonsAPI;
+    /** Manage secrets and environment variables. */
+    readonly secrets: SecretsAPI;
+    /** Manage custom domains. */
+    readonly domains: DomainsAPI;
+    /** Query CPU, memory, network, disk, and cost metrics. */
+    readonly metrics: MetricsAPI;
     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 })
-     * ```
+     * @requires `project` to be set in the constructor.
      */
     create(template?: string, opts?: Omit<SandboxOpts, 'project' | 'projectId'>): Promise<Sandbox>;
     /** Connect to an existing sandbox by ID (resumes it if paused). */
@@ -578,4 +965,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, Lizard, LizardError, type LizardOpts, NotFoundError, type ProcessOpts, type ProcessResult, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, TimeoutError, Volume, type VolumeInfo, resolveProjectId };
+export { type Addon, type AddonType, AuthenticationError, type CodeContext, CodeSandbox, type ConnectionOpts, type CostMetrics, type CreateAddonOpts, type CreateContextOpts, type CreateProjectOpts, type CreateServiceOpts, type CreateVolumeOpts, type DeployEvent, DeployHandle, type DomainInfo, Execution, ExecutionError, type FileInfo, type FsOpts, Lizard, LizardError, type LizardOpts, type LogLine, type MetricPoint, type MetricRange, NotFoundError, type ProcessOpts, type ProcessResult, type Project, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, type ScaleOpts, type Secret, type Service, type ServiceMetrics, type SetSecretOpts, TimeoutError, Volume, type VolumeInfo, resolveProjectId };