Installation

Better Compute is split into @better-compute/* packages. Most applications install the umbrella package, better-compute, which depends on all of them and re-exports each one as a subpath. A subpath loads only when you import it, and the server never imports the injected modules (provision, metal, vps): your application imports them and passes them in, so what you do not use costs nothing at run time.

Requirements

Compute's own store is PostgreSQL or PGlite only. It needs EXCLUDE constraints, SKIP LOCKED and range types, so there is no SQLite adapter for it. Embedded Better IAM can still use Better IAM's SQLite adapter in development.

Install from npm

npm install better-compute better-iam

npm install @electric-sql/pglite

npx better-compute --help
npx better-compute init   # writes better-compute.config.ts

With pnpm, list the Better IAM packages Better Compute imports as your own dependencies, so the optional peers resolve under pnpm's strict layout, and allow the native builds (allowBuilds for argon2 and better-sqlite3 in pnpm-workspace.yaml):

pnpm add better-compute better-iam @better-iam/server @better-iam/core @better-iam/adapter-sqlite @electric-sql/pglite

Then import the subpaths you need:

import { betterCompute } from 'better-compute';
import { metal } from 'better-compute/metal';
import { postgres } from 'better-compute/postgres';
import { createComputeClient } from 'better-compute/client';

Each package is also published on its own as @better-compute/<name>, for services that need only part of the platform, for example a browser bundle that needs only @better-compute/client.

Install from a clone

To work on Better Compute itself, or to try changes that are not released, build it from the repository. The workspace pins pnpm 11.19.0: install with that version once, then run the pinned copy from node_modules.

git clone https://github.com/better-compute/better-compute.git
cd better-compute
npx pnpm@11.19.0 install
node node_modules/pnpm/bin/pnpm.mjs build   # tsc -b: every package's dist/

Better IAM resolves from npm like any other dependency. The better-compute command is then packages/cli/dist/index.js; the quickstart shows how to put it on your path and run the repository's example configuration. To use the local build in another project, pack:all writes one tarball per package to artifacts/ (@better-compute/core@0.1.0 becomes artifacts/better-compute-core-0.1.0.tgz) without publishing anything; install those in place of the registry versions. The repository's packed smoke test (pnpm test:packed) does exactly that in a fresh consumer. Local development covers the workspace scripts.

Subpath imports

The umbrella's subpaths are generated from packages/better-compute/umbrella.json; each one is a one-line re-export of its package, and nested subpaths map to nested exports of the same package.

defineMethod comes from better-compute/core, defineStep and defineProfile from better-compute/provision, and defineProvider from better-compute/vps.

Built-in and injected modules

inventory and capacity are built in: betterCompute() always registers them (after the node controllers), and their groups (inventory, pools, capacity, reservations, quotas) exist in every deployment. Everything else is a module you pass in modules:

import { betterCompute } from 'better-compute';
import { eventsModule } from 'better-compute/events';
import { fleetModule } from 'better-compute/fleet';
import { metal } from 'better-compute/metal';
import { postgres } from 'better-compute/postgres';
import { provisionModule } from 'better-compute/provision';
import { vps } from 'better-compute/vps';

const secret = process.env.BETTER_COMPUTE_SECRET!; // at least 32 characters
const bareMetal = metal();

export const compute = betterCompute({
  database: postgres({ url: process.env.BETTER_COMPUTE_DATABASE_URL! }),
  secret,
  baseURL: 'https://compute.example.com',
  rootTenantId,
  iam,
  // provision runs metal's workflows; metal contributes its verbs, steps and profiles
  modules: [provisionModule({ modules: [bareMetal] }), bareMetal, vps(), eventsModule({ secret }), fleetModule()],
});

The API types follow the modules: client.instances exists only when vps() is in modules. The repository enforces the direction with scripts/check-deps.mjs: @better-compute/server never depends on provision, metal, vps, gateway, iam, postgres, a provider or a driver. See modules.

Packages outside the umbrella

These are installed directly, not through better-compute:

Nothing in packages/ imports a @better-compute/provider-* package; you pass providers to vps() yourself. See providers.

Optional peers

The umbrella declares these as optional peer dependencies. Install the ones you use; better-iam brings all of the @better-iam/* ones:

@better-compute/cli also declares @better-compute/testing as an optional peer, for dev --sim and sim; the umbrella depends on it, so installing better-compute provides it. See Better IAM for how the two products fit together.

The daemon

bcd is not an npm package. It is designed as a Go binary for Linux on amd64 and arm64, released by goreleaser as bcd_<version>_linux_{amd64,arm64}.tar.gz with a .sha256, plus the bare binaries for machines, and listed in an offline-signed release manifest (better-compute release sign). better-compute daemon install-script already writes the POSIX installer: it downloads the pinned binary from {base-url}{base-path}/downloads/bcd/{version}/linux-{arch}, checks its SHA-256, writes /etc/bcd/config.toml and a hardened bcd.service, and runs bcd join. The control plane serves that download route when you configure downloads (see serving the binaries).

No binary is released yet. daemon/ is a Go module whose v0.1 node agent is built and tested: bcd join, bcd node and bcd status run end to end against a real gateway in tests/e2e/bcd.test.ts. What is missing is a release (goreleaser is configured but has not run), a run on a real GPU host (GPUs are read through nvidia-smi, cb987e5), and the later modes. You can build it yourself with Go 1.26 or later (go build ./cmd/bcd in daemon/). The TypeScript FakeDaemon in better-compute/testing speaks the real protocol for everything else. See installing the daemon.

All packages

Verify the installation

doctor loads your configuration and checks the database, the schema, the clock and the method registry without changing anything:

better-compute migrate
better-compute doctor --strict

It runs compute.selfCheck() (applied migrations, btree_gist, compute_now() against the database clock, every method's IAM action, each module's own checks) and adds the CLI's findings, such as iam.not-configured when no Better IAM is wired in. --strict exits non-zero with DOCTOR_FINDINGS on any warning, so you can run it in CI. See the CLI reference.

Next steps