instavm 0.15.0 → 0.17.0

package/README.md

@@ -45,9 +45,18 @@ printf '%s' "$INSTAVM_API_KEY" | instavm auth set-key
 ```bash
 instavm whoami
 instavm ls
+instavm ls -a
+instavm ls --watch
 instavm create --type computer-use --memory 4096
 instavm connect vm_123
+instavm deploy
+instavm deploy --plan
 instavm snapshot ls
+instavm snapshot get <snapshot_id> --watch
+instavm egress get --session <session_id>
+instavm exec --cmd "print('hello from instavm')"
+instavm browser read https://example.com
+instavm browser screenshot https://example.com --out page.png
 instavm volume ls
 instavm volume files upload <volume_id> ./README.md --path docs/README.md
 instavm share create vm_123 3000 --public
@@ -55,23 +64,80 @@ instavm share set-private <share_id>
 instavm ssh-key list
 instavm desktop viewer <session_id>
 instavm doc
-instavm billing
+instavm billing portal
+instavm login
+instavm tape ls
+instavm vault list
+instavm desktop recordings ls
 ```
 
+`instavm ls` shows active VMs only. Use `-a` or `--all` to include terminated VM records. On ANSI terminals the human-readable list uses colored status badges, and both `instavm ls` and `instavm snapshot get` support `--watch` for periodic refreshes.
+
+### Cookbooks
+
+`instavm cookbook` pulls curated starter apps from the public [`instavm/cookbooks`](https://github.com/instavm/cookbooks) catalog, creates a VM, starts the service, creates the share, and returns the public URL.
+
+```bash
+instavm cookbook list
+instavm cookbook info neon-city-webgl
+instavm cookbook deploy neon-city-webgl
+instavm cookbook deploy hello-fastapi
+instavm cookbook deploy my-app --vault vault_a --vault vault_b
+instavm deploy ./app --no-vault
+```
+
+The CLI syncs the cookbook repo into `~/.instavm/cookbooks/`, checks for `git`, `ssh`, `scp`, and `tar`, prompts for any required secrets, and auto-registers a local public SSH key if your account does not already have one.
+
+### Deploy
+
+`instavm deploy` tries to deploy the app in the current directory without asking you to create an `instavm.yaml` first. It detects a simple Node.js or Python web app, creates a VM, uploads the project, starts the service, and gives you a share URL.
+
+```bash
+instavm deploy
+instavm deploy --plan
+instavm deploy ./path/to/app
+```
+
+`--plan` shows the detected runtime, install command, start command, port, and secrets without creating a VM.
+
+`instavm deploy` is experimental right now. The zero-config path is working best for straightforward Node.js and Python apps. Some runtimes and projects still need follow-up fixes or backend support.
+
 ### Command Reference
 
 - `auth`: `set-key`, `status`, `logout`
+- `login`: browser PKCE login (writes profile API key)
 - `whoami`: show account details and SSH keys
-- `create`/`new`, `ls`/`list`, `rm`/`delete`, `clone`, `connect`: core VM workflows
+- `ls`/`list`: show active VMs by default; use `-a` or `--all` for all VM records
+- `cookbook`: `list`, `info`, `deploy` for curated starter apps from `instavm/cookbooks`
+- `deploy`: experimental zero-config deploy for the current app directory
+- `create`/`new`, `rm`/`delete`, `clone`, `connect`: core VM workflows
 - `snapshot`: `ls`, `create`, `build`, `get`, `rm`
-- `desktop`: `status`, `start`, `stop`, `viewer`
+- `egress`: `get`, `set` for VM and session egress policies
+- `exec`: run inline commands, local files, or fetch async task results
+- `browser`: `read`, `screenshot`; `browser session` (`create`, `close`, `ls`); `navigate`, `click`, `type`, `fill`, `scroll`, `wait`, `extract`
+- `desktop`: `status`, `start`, `stop`, `viewer`; `desktop recordings` (`ls`, `get`, `download`, `rm`)
+- `vm`/`vms`: includes `vm update` (memory, snapshot-on-terminate, snapshot name)
+- `tape`: `ls`, `get`, `start`, `stop`, `events`, `diff`, `branch`, `play`, `lanes`, `export`, `rm`
+- `vault` / `secrets` / `secret`: vault CRUD, secrets, services, `setup`, `catalog`, `logs`, `discover`
+- `pty`: attach PTY shell to a VM over WebSocket
+- `billing`: `portal`, `status`, `allocation`, `usage`, `usage-history`, `check`, `rates`, `trends`, `forecast`
 - `volume`: `ls`, `get`, `create`, `update`, `rm`, `checkpoint`, `files`
 - `share`: `create`, `set-public`, `set-private`, `revoke`
 - `ssh-key`: `list`, `add`, `remove`
-- `doc`/`docs`, `billing`: docs and billing links
+- `doc`/`docs`: docs links
 
 All leaf commands support `--json`. Share visibility updates use `share_id`, which matches the public API.
 
+Examples:
+
+```bash
+instavm egress set --session <session_id> --no-allow-package-managers --deny-http --domain pypi.org
+instavm exec ./script.py
+instavm exec result <task_id>
+instavm browser read --session <browser_session_id>
+instavm browser screenshot https://example.com --out ./page.png
+```
+
 ## Library Quick Start
 
 ```typescript
@@ -88,13 +154,44 @@ console.log(me.email);
 console.log(vms.length);
 ```
 
+## Parity with Python `sandbox_client`
+
+This package tracks **API and CLI parity** with the official Python distribution **`instavm`** in **[sandbox_client](https://github.com/BandarLabs/sandbox_client)** (baseline **~0.23.0**: `instavm/sandbox_client.py`, `instavm/cli.py`, `instavm/_cookbook.py`). The **npm semver line is independent** of Python’s `pyproject.toml` version—see [Changelog](#changelog).
+
+**Naming:** the JS `InstaVM` client uses **camelCase** methods; several Python-style operations are also exposed as thin delegators on `InstaVM` (for example vault helpers) for readability across languages.
+
+**Not available in this JS SDK** (by design; tied to the Python ecosystem or deferred):
+
+- `instavm.integrations.openai_agents` (`InstaVMSandboxClient`)
+- `instavm.integrations.mounts` (`InstaVMCloudBucketMountStrategy`)
+- `cassette_replay`–style HTTP transports
+
+### Optional LLM integrations
+
+Subpath exports match the Python integration modules. Install **optional peers** only for the stack you use:
+
+| Import path | Purpose | Typical optional deps |
+|-------------|---------|------------------------|
+| `instavm/integrations/openai` | `getOpenAITools`, `executeToolCall` | none (uses your OpenAI client) |
+| `instavm/integrations/azure-openai` | Same tools + `getSystemPrompt` | — |
+| `instavm/integrations/langchain` | `getLangchainTools()` | `@langchain/core` |
+| `instavm/integrations/llamaindex` | `getLlamaIndexTools()` | `llamaindex`, `zod` |
+| `instavm/integrations/ollama` | `getOllamaTools`, `executeOllamaTool`, `OllamaAgent` | none (uses `fetch` to Ollama) |
+
+```typescript
+import { getOpenAITools, executeToolCall } from 'instavm/integrations/openai';
+```
+
 ## Table of Contents
 
 - [CLI](#cli)
   - [Auth & Config](#auth--config)
   - [Common Commands](#common-commands)
+  - [Cookbooks](#cookbooks)
+  - [Deploy](#deploy)
   - [Command Reference](#command-reference)
 - [Library Quick Start](#library-quick-start)
+- [Parity with Python `sandbox_client`](#parity-with-python-sandbox_client)
 - [Code Execution](#code-execution)
   - [Cloud Mode](#cloud-mode)
   - [Local Mode](#local-mode)
@@ -468,12 +565,16 @@ try {
 ## Development & Testing
 
 ```bash
-npm install          # Install dependencies
-npm run test:unit    # Unit tests
-npm test             # Full test suite
-npm run build        # Build package
+npm install           # Install dependencies
+npm run test:unit     # Unit tests (includes a repo scan for accidental secret patterns)
+npm run build && npm run test:smoke   # After a build: CLI + dist SDK smoke checks
+npm test              # Full vitest default suite
+npm run test:e2e      # Live API tests — only when INSTAVM_API_KEY is set (see tests/integration/README.md)
+npm run build         # Build package
 ```
 
+Do **not** commit real API keys or `.env` files. Use placeholders in docs/tests (`your_api_key`, `instavm_sk_test`, `test-api-key`) and keep production keys in environment variables or GitHub Actions **secrets**.
+
 ---
 
 ## Further Reading
@@ -489,7 +590,30 @@ npm run build        # Build package
 
 ## Changelog
 
-Current package version: **0.15.0**
+When checking **SDK / CLI parity** with the official Python client, use a checkout of **[sandbox_client](https://github.com/BandarLabs/sandbox_client)** (for example `~/Documents/projects/sandbox_client` — there is typically no `Documents/project/` path). Treat **`[project] version` in that repo’s `pyproject.toml`** as the API parity baseline. Diff `instavm/sandbox_client.py` and `instavm/cli.py` against this SDK when adding or reviewing APIs.
+
+**npm semver is independent** of the Python package version: this JS library advances on its own minor/patch line (for example **0.16.x → 0.17.0**) and does not mirror Python’s `pyproject.toml` version number.
+
+Current npm package version: **0.17.0**
+
+### 0.17.0
+
+- Broad parity with Python **sandbox_client ~0.23.0**: tapes, vaults, PTY, recordings, credits, session/usage helpers, client-level browser APIs, cookbook/deploy vault flags (`--vault`, `--no-vault`, `--no-setup-vault`), expanded CLI (`login`, `billing`, `tape`, `vault`, `pty`, `vm update`, browser subcommands, `desktop recordings`), and integration entry points (`integrations/openai`, `azure-openai`, `langchain`, `llamaindex`, `ollama`)
+- Added colored VM status badges, `--watch` refreshes for `ls` and `snapshot get`, and snapshot-build spinner coverage (from earlier 0.17 work)
+
+### 0.16.1
+
+- Fixed deploy and cookbook uploads through the SSH gateway by forcing legacy SCP mode
+
+### 0.16.0
+
+- Expanded CLI docs for `instavm cookbook`
+- Added experimental `instavm deploy` for zero-config app deploys from the current directory
+
+### 0.15.1
+
+- `ls` now matches the SSH gateway: active VMs by default, `-a` or `--all` for all VM records
+- `whoami` now uses the live `/v1/users/me` endpoint
 
 ### 0.15.0