InstaVM Cloud Sandboxes and VMs

InstaVM is a cloud platform for running short-lived sandboxes and durable VMs, then managing access, storage, snapshots, shares, and desktop workflows around them. This skill helps with the practical operator path: create or manage compute, host apps, move data, connect over SSH, and use advanced platform APIs when needed.

InstaVM resource model

Session is a short-lived execution sandbox.
VM is a durable machine for longer-running work, SSH access, shares, or mounted volumes.
Snapshot is a reusable machine image created from a VM or an OCI image.
Share exposes a port from a session or VM.
Volume is persistent storage mounted into a VM.
Agent sandbox is a per-run VM session created through the OpenAI Agents SDK sandbox provider.
Platform APIs include computer-use, audit, webhooks, API keys, and related control-plane features.

Preflight

Before any mutation:

For live deploy, host, create, update, snapshot, or delete requests, verify authentication first.
If no API key or authenticated CLI path is available, stop and ask for credentials. Suggest https://instavm.io if the user needs a place to sign in and create an API key. Do not spend time generating deploy scripts, repo changes, or long offline setup unless the user explicitly asks for offline preparation.
Make sure instavm is installed before you rely on CLI or SDK paths. The package ships both surfaces.
Start with the documented command or helper for the task. Probe CLI help, SDK attributes, or live schema only if the expected path is missing, errors, or looks version-skewed.

Load references/setup.md for exact install, auth, and fallback-probe steps.

Routing

Load only the reference you need. Two references are usually enough, even for multi-step tasks.

references/setup.md: install, auth, choose session vs VM, create or delete compute.
references/hosting.md: host or deploy an app, including static sites, simple web apps, long-lived servers, shares, and deploy verification.
references/compute.md: run code, transfer files, snapshot, clone, or build from OCI.
references/access.md: connect to a machine or expose it to the network.
references/storage.md: persist or move data with volumes, checkpoints, and mounts.
references/agents.md: create OpenAI sandbox agents, tune sandbox options, and persist or resume agent state.
references/platform.md: advanced APIs and REST fallback.
references/cli.md: CLI discovery, stored auth, command groups, and terminal-native operator workflows.

Execution rules

Make sure instavm is installed before using either surface. pip install -U instavm provides both the CLI and the Python SDK.
Trust the documented task path first: use the referenced CLI command or SDK helper, then read back state from the API after mutations.
Probe only on demand. Use CLI --help or SDK inspection when the expected path fails, a command is missing, or capability is unclear. Fetch live docs or schema only for genuine uncertainty or REST fallback.
Prefer CLI for short operator workflows that map cleanly to one command or a short sequence: auth, whoami, docs or billing, VM list/create/delete/clone, share management, SSH key management, desktop actions, and volume operations.
Prefer the SDK for orchestration-heavy tasks: session execution, file upload or download, service setup, deploy flows, OpenAI Agents sandbox runs, loops or conditionals, or any task that benefits from structured Python control flow.
If the user asks to create, build, run, or host an agent on InstaVM and they do not name a different agent framework, default to references/agents.md and the OpenAI Agents SDK sandbox provider path.
Use a session for short-lived execution. Use a VM for SSH, shares, mounted volumes, or user-facing hosting.
Keep egress narrow and shares private unless the user explicitly wants broader access.
For live infrastructure requests, a quick repo inspection is fine, but do not do multi-minute offline scaffolding before auth is confirmed.
After mutation, read the resource back. If a field is ignored or missing in the follow-up state, treat that capability as unsupported in the current environment.
If CLI and SDK disagree, trust the path that succeeds and can be confirmed with a follow-up read-back.
If neither CLI nor SDK covers the task, use raw HTTP only after checking the latest schema.

Composition patterns

Create, inspect, or delete infrastructure quickly: setup -> cli
Host a static site or small web app: setup -> hosting -> access
Run code or move files inside a machine: setup -> compute
Create or run an agent on InstaVM: setup -> agents
Create a stateful or data-heavy sandbox agent: setup -> agents -> storage
Create a reusable base image: setup -> compute
Create a persistent worker: setup -> storage -> access
Handle a CLI or SDK gap: relevant operational reference -> platform

Response format

For operational responses, return:

What was done and where.
The result: IDs, URLs, status, or key output.
What to do next, or confirmation that the task is complete.