Platform SDK

Planned public API. @domainruntime/platform exists and powers the CLI, but it is not yet on npm and today's calls differ: init({ auth: { token }, runtime, sandbox }), platform.environments.resolve / pull / pushDomain(handle, domain, options) and platform.sandboxes.up / pull / run / down. Errors are PlatformApiError, with the code in message, plus status and body.

The Platform SDK is how you manage DomainRuntime from code: build a product on top of it, give an agent its own environment, run tests in sandboxes, or automate releases in CI. The CLI is built on it.

npm i @domainruntime/platform

Authenticate

import { init } from "@domainruntime/platform";

// on a backend or in CI
const platform = init({ serviceKey: process.env.DOMAIN_SERVICE_KEY! });

// as a person, reusing the CLI's login
const platform = init({ auth: "cli" });

Projects and environments

const project = await platform.projects.create({ name: "Orders" });

const env = await platform.environments.create({
  project: project.id,
  name: "staging",
  mode: "dev",
});
// env.handle, env.url

const same = platform.environments.get("dev-orders-staging-3k9x2m7q");
await platform.environments.list({ project: project.id });
await env.delete();

Publish a domain

import domain from "../src/domain";

const result = await env.pushDomain(domain);
// result.pushId, result.digest

pushDomain takes the domain itself: schema, actions and their contracts come from your code, not from a file you maintain by hand.

Run things

await env.query({ orders_order: { $: { limit: 10 } } });
await env.actions.run("orders.place", { orderId: crypto.randomUUID(), total: 10 });
const { token } = await env.users.mintToken({ id: userId, email });

Sandboxes

const sandbox = await platform.sandboxes.create({ env: "dev-orders-e2e-4k2m9x1p" });
await sandbox.pushDomain(domain);
// … the same API as an environment …
await sandbox.destroy();

See Sandboxes.

Releases

const release = await env.releases.create();   // build the project's source and activate it
await env.releases.rollback();

Keys

const { key } = await platform.keys.create({ name: "backend", env: env.handle });
await platform.keys.revoke(keyId);

Errors

Every method throws PlatformApiError with status and a stable code, such as environment_not_found or catalog_migration_required. See Errors.

On this page