Morph
A sandbox per MorphCloud instance. Snapshot-first VMs with instant branching, via the morphcloud SDK.
Installation
morphcloud is an optional peer dependency of sbox-sdk, loaded lazily on first use.
pnpm add sbox-sdk morphcloudUsage
import { createSandboxClient } from "sbox-sdk";
import { morph } from "sbox-sdk/morph";
const client = createSandboxClient({
provider: morph({ apiKey: process.env.MORPH_API_KEY! }),
});
// `template` is a snapshot id (booted directly) or an image to snapshot first.
const sandbox = await client.create({ template: "morphvm-minimal" });
const res = await sandbox.commands.run("uname -a");
console.log(res.stdout);
// Morph's signature move: branch the live instance into N forks.
const forks = await sandbox.snapshots!.fork(3);Morph is snapshot-first — there's no boot-from-image, so create() either boots a snapshot… template directly or lazily builds a snapshot from an image (imageId, resources) and boots that.
Exec is the buffered instance.exec(cmd) (streaming emulated); it has no
per-command cwd/env, so the core folds those into a cd … && KEY=v …
wrapper (perCommandEnvCwd: false). Files are read and written via exec +
base64. Ports are public HTTP services (exposeHttpService).
snapshots.create() is instance.snapshot() and fork() is
instance.branch() — both native; in-place restore is not supported
(branching makes new instances). destroy() stops the instance; there is no
separate pause.
Authentication
A single API key.
| Option | Env var | Required | Description |
|---|---|---|---|
apiKey | MORPH_API_KEY | required | MorphCloud API key. |
baseUrl | — | optional | Override the MorphCloud API base URL. |
imageId | — | optional | Default image to snapshot from when `template` is not a snapshot id (default "morphvm-minimal"). |
vcpus | — | optional | Default vCPUs for a lazily-created snapshot. |
memory | — | optional | Default memory (MB) for a lazily-created snapshot. |
diskSize | — | optional | Default disk size for a lazily-created snapshot. |
Morph is snapshot-first: pass a snapshot id as `template` to boot it directly, or any other value as an image to snapshot first.
Options
Prop
Type
Capabilities
| Capability | Level | Notes |
|---|---|---|
list | native | |
snapshot / fork | native | instance.snapshot() / branch() |
streaming | emulated | instance.exec is buffered |
filesUpload | native | via exec + base64 |
exposePort | native | exposeHttpService |
codeInterpreter | unsupported | |
pause / stop | unsupported | destroy() = stop instance |
perCommandEnvCwd is false (core wraps); previewModel is subdomain. In-place snapshot restore reports NotSupported.