# Platform SDK

URL: https://docs.domainruntime.dev/docs/platform/platform-sdk
Status: Planned
Reviewed: 2026-09-22



<div className="docs-note">
  **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`

  .
</div>

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](/docs/platform/cli) is built on it.

```bash
npm i @domainruntime/platform
```

## Authenticate [#authenticate]

```ts
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 [#projects-and-environments]

```ts
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 [#publish-a-domain]

```ts
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 [#run-things]

```ts
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 [#sandboxes]

```ts
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](/docs/environments/sandboxes).

## Releases [#releases]

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

## Keys [#keys]

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

## Errors [#errors]

Every method throws `PlatformApiError` with `status` and a stable `code`, such as `environment_not_found` or `catalog_migration_required`. See [Errors](/docs/reference/errors).