@lizard-build/sdk 0.1.34 → 0.1.36

package/README.md

@@ -80,40 +80,74 @@ print(f"Live at https://{sandbox.get_host(3000)}")
 sandbox.kill()
 ```
 
-## Pause and Resume
+## Persisting Work Across Sandboxes
 
-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.
+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 `/data` that a later sandbox re-attaches.
 
-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.
+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
-// 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 (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)
-await resumed.kill()
+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" > /data/notes.txt')
+await first.kill()          // sandbox gone, /data survives
+
+const second = await lizard.create('codex', { volumeName: 'agent-scratch' })
+console.log(await second.fs.read('/data/notes.txt'))   // "notes"
 ```
 
 ```python
-# 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 = lizard.connect(sandbox_id)
-result = resumed.process.exec_("python -c 'import sklearn; print(sklearn.__version__)'")
-print(result.stdout)
-resumed.kill()
+vol = lizard.volumes.get_or_create("agent-scratch", size_gb=10)
+
+first = lizard.create("codex", volume_name="agent-scratch")
+first.process.exec_('echo "notes" > /data/notes.txt')
+first.kill()                # sandbox gone, /data survives
+
+second = lizard.create("codex", volume_name="agent-scratch")
+print(second.fs.read("/data/notes.txt"))   # "notes"
+```
+
+Note that only `/data` survives — installed packages and in-memory state do not. Bake tooling into a template instead of reinstalling it per sandbox.
+
+> `pause()` / `resume()` exist on the client but are **not implemented** for the current runtime and always fail with HTTP 501. Use a volume.
+
+## 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.
+
+```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
+})
+await sandbox.process.exec('lizard volume list')   // sees only this workspace
 ```
 
+```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.
+
 ## API
 
 ### `new Lizard({ project, apiKey?, apiUrl?, timeoutMs? })`
@@ -137,7 +171,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.
+Connect to an existing sandbox by ID. Throws `NotFoundError` if it has been killed or has expired.
 
 ### `Sandbox.list(opts?)`
 
@@ -145,6 +179,38 @@ 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()` |
+| `lizard.whoami()` | The account behind the credential — works for scoped keys too |
+| `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.
+
+---
+
 ### `sandbox.fs`
 
 Read and write files inside the microVM filesystem.
@@ -179,7 +245,7 @@ const url = sandbox.getHost(3000)
 
 ### `sandbox.pause()` / `sandbox.resume()`
 
-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.
+**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()`