@omg-dev/sandbox

Server-only control-plane client and TypeScript template baker for Vibes sandboxes. This is deliberately separate from @omg-dev/sdk/sandbox, which is the restricted router available to code running inside a user sandbox.

Public usage (API key)

Get an API key (omg_sk_…) from the omg.dev dashboard and point the client at the public API — see docs.omg.dev/sandbox:

import { SandboxClient } from "@omg-dev/sandbox";

const client = new SandboxClient({
  baseUrl: "https://infra.omg.dev",
  token: process.env.OMG_API_KEY!, // omg_sk_...
});

const sandbox = await client.create({ templateId: "react-ts", ports: [5173] });
await sandbox.exec("echo", ["hello from a microVM"]);
await sandbox.snapshot();
await sandbox.stop();

Template baking (service / self-host)

import {
  SandboxClient,
  apt,
  bakeTemplate,
  check,
  defineTemplate,
  run,
} from "@omg-dev/sandbox";

const template = defineTemplate({
  id: "my-agent",
  version: "1",
  title: "My agent",
  ports: [3000],
  install: [
    apt.packages(["tmux"]),
    run({ user: "user", command: "bun install -g [email protected]" }),
  ],
  checks: [check.command("tmux"), check.command("my-agent", { user: "user" })],
  start: {
    user: "user",
    command: "my-agent serve --host 0.0.0.0 --port 3000",
    readiness: { port: 3000 },
  },
});

const client = new SandboxClient({
  baseUrl: process.env.VIBES_SANDBOX_URL!,
  token: process.env.VIBES_INFRA_SERVICE_TOKEN!,
  ownerId: "user-or-org-id",
});

await bakeTemplate(client, template);

bakeTemplate creates a raw sandbox, applies each typed step, verifies checks, writes a generic boot contract, snapshots it, waits for durable upload, and publishes both my-agent-v1 and my-agent (latest). Direct service clients publish an immutable version in the global system catalogue; clients with an ownerId publish both names in that user's private namespace. A deployment consumes either with { templateId: "my-agent-v1" } or { templateId: "my-agent" }.

Publication also records the compiled start command, ports, and readiness probe in the template registry. Creation copies that executable contract onto the sandbox row, so hibernate/resume never re-reads mutable registry state and a later latest publish cannot change an existing sandbox.

Repository templates live at templates/<id>/template.ts. The existing Build Templates workflow discovers them and uses the same baker. agent-catalog.ts is the source of truth for the first-party coding-agent images.

Never import this package in browser code: its client accepts privileged API credentials. User-authenticated server routes may instantiate it with the caller's token and owner ID; install commands still run only inside the Firecracker guest.