SDK

npm install @beamcloud/beam-js@1.1.4
export BEAM_TOKEN=YOUR_BEAM_TOKEN

import { beamOpts, VM } from "@beamcloud/beam-js";

beamOpts.token = process.env.BEAM_TOKEN || "";
beamOpts.workspaceId = process.env.BEAM_WORKSPACE_ID || "";

const vm = await VM.create({
  name: "agent-workspace", // optional; otherwise generated
  cpu: 1, // cores, or "1000m"
  memory: "2Gi", // MiB or a quantity
  desktop: true,
  protectedPorts: [7681, 8080],
  idleTimeout: 300, // idle seconds; 0 keeps running
  idleAction: "pause", // "stop" or "pause"
  autoResume: true,
});

const command = await vm.exec(["node", "--version"]);
await command.wait({ timeoutMs: 30_000 });
console.log(await command.stdout.read());

await vm.fs.writeText("/workspace/hello.txt", "hello");
const png = await vm.desktop.screenshot("./desktop.png");
await vm.pause();
await vm.close(); // close local tunnels/watchers

const existing = await VM.get("agent-workspace"); // read-only: does not start it
const ready = await VM.connect(existing.id); // starts/resumes and waits
const fleet = await VM.list({
  metadata: { user_id: "123" },
  status: "running",
});

await ready.refresh();
console.log(ready.id, ready.name, ready.status, ready.spec, ready.metadata);
console.log(ready.info); // full typed management response
await ready.wait({ services: true }); // also wait for SSH/UI ports
await ready.update({ idleTimeout: 60, idleAction: "pause", autoResume: true });
await ready.update({ metadata: {} }); // replaces the whole map
await ready.stop(); // keep root; cold boot next time
await ready.start();
await ready.pause(); // keep RAM and running processes
await ready.resume();
await ready.start({ cold: true }); // explicitly discard saved RAM
await ready.remove(); // delete VM and its managed root

const snapshot = await vm.snapshots.create("before-edit");
console.log(snapshot.id, snapshot.name, snapshot.info);
const snapshots = await vm.snapshots.list(); // only this VM's snapshots
const all = await VM.snapshots.list(); // workspace, including old sources
const saved = await VM.snapshots.get("before-edit");

const branch = await saved.fork({ name: "experiment", cpu: 2 });
// Equivalently: VM.create({ name: "experiment", snapshot: saved.id })
const current = await vm.fork("current-root-copy");

const template = await vm.templates.create({
  name: "dev-base",
  description: "Tools installed",
});
const templates = await VM.templates.list();
const seed = await VM.templates.get("dev-base");
const next = await seed.fork({ name: "next-agent", desktop: false });
// Equivalently: VM.create({ name: "next-agent", template: seed.id })

await vm.snapshots.delete(snapshot.id);
await VM.templates.delete(template.id);
// Artifact handles also support snapshot.delete() / template.delete().

const controller = new AbortController();
const command = await vm.exec(["cat"], {
  stdin: "literal text 😀\n",
  cwd: "/workspace",
});
await command.wait({ timeoutMs: 10_000, signal: controller.signal });
console.log(await command.stdout.read(), await command.stderr.read());

const server = await vm.execShell("npm run dev", {
  env: { NODE_ENV: "development" },
});
for await (const line of server.logs) console.log(line);
const processes = await vm.listProcesses();
const reattached = await vm.getProcess(server.pid, {
  containerId: server.containerId,
});
await reattached.kill();

await vm.keepAlive(async () => {
  const job = await vm.exec(["./long-job"]);
  await job.wait();
});

const journal = await vm.logs({ unit: "beam-terminal.service", lines: 200 });
console.log(await journal.read());
const live = await vm.logs({ session: "prompt-abc123", follow: true });
for await (const line of live) console.log(line);
await live.close(); // stop the log-follow process

const foreground = await vm.prompt("add tests", {
  agent: "codex",
  cwd: "/workspace",
});
const session = await vm.prompt("add tests", {
  agent: "claude",
  background: true,
});

const login = await vm.execShell(
  "printenv OPENAI_API_KEY | codex login --with-api-key",
);
if ((await login.wait()) !== 0) throw new Error(await login.stderr.read());

import { Image, Volume } from "@beamcloud/beam-js";

const image = await Image.fromDockerfile("./Dockerfile", ".");
const custom = await VM.create({
  image,
  env: { APP_MODE: "dev" },
  secrets: ["API_KEY"],
  volumes: [new Volume("shared", "/data")],
  disks: [{ name: "cache", size: "10Gi", mountPath: "/cache" }],
  dockerEnabled: true,
});
const prepared = await VM.prepareImage(image, { desktop: true });
const built = await prepared.build(); // standalone VM image build
if (!built.success || !built.imageId) throw new Error("VM image build failed");
const fromId = await VM.create({ image: Image.fromId(built.imageId) });

await custom.docker.version();
await custom.docker.run("hello-world", ["--rm"]);
await custom.docker.compose(["up", "-d"]);
await custom.docker.exec(["ps"]);

const url = await vm.exposePort(3000, { protected: true });
const stable = await vm.getUrl(3000);
const token = await vm.getAccessToken();
const response = await fetch(url, { headers: { "X-Beam-VM-Token": token } });
const browserEntry = await vm.accessUrl(3000, { ttl: 600 });
await vm.rotateAccessToken(); // revoke token and browser sessions
await vm.unexposePort(3000);
await vm.updateNetworkPermissions(false, ["10.0.0.0/8"]);

const forward = await vm.portForward(5432); // private localhost TCP port
console.log(forward.host, forward.port, forward.url);
await forward.close();
const stream = await vm.tunnel(5432); // Node Duplex; authenticated WebSocket
stream.write(Buffer.from("bytes"));
stream.close();

await vm.ssh(["uname", "-a"]); // omit command for an interactive shell
await vm.scp("./file.txt", "vm:/workspace/file.txt");
await vm.scp("vm:/workspace/file.txt", "./download.txt");
const watcher = await vm.sync("./project", { watch: true });
await watcher.close();

await vm.desktop.press("ctrl+l");
await vm.desktop.write("https://example.com\n");
await vm.desktop.press("Return");
const recording = await vm.desktop.record("/workspace/screen.mp4", { fps: 30 });
await vm.desktop.stopRecording(recording);
await vm.fs.downloadFile("/workspace/screen.mp4", "./screen.mp4");