# Installation (/docs/guides/installation)

> Requirements, installing better-compute and Better IAM from npm, the umbrella package's subpaths, packages outside it, optional peers, and building from a clone.



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.

> **Version 0.1.1.** 
  `better-compute` and every `@better-compute/*` package are published to npm at 0.1.1, on the `latest` dist-tag,
  and accept Better IAM `>=0.2.0 <0.4.0` (`better-iam` and `@better-iam/*`; 0.3 is current), which is on npm too. The Go daemon `bcd` is
  not an npm package and has no released binary yet; see [the daemon](#the-daemon).

## Requirements [#requirements]

| Requirement                            | Notes                                                                                                                                                                                                    |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Node.js 22.12 or newer                 | The `engines` field of every package. CI runs Node.js 22 and 24 on Ubuntu and Windows. A TypeScript configuration file (`better-compute.config.ts`) needs 22.18 or newer, which strips types by default. |
| ESM                                    | Every package is an ES module with TypeScript declarations and `{ types, import }` exports only. Use `"type": "module"` or a bundler.                                                                    |
| PostgreSQL 16 or newer                 | The production store; CI runs PostgreSQL 17. The first migration creates the `btree_gist` extension, which the booking constraint needs. PgBouncer in transaction mode is supported.                     |
| PGlite, for development                | PostgreSQL in WebAssembly, through the optional peer `@electric-sql/pglite`. One connection, with transactions serialized. `btree_gist` works on it.                                                     |
| Native builds, for embedded Better IAM | Better IAM's SQLite adapter and password hashing use `better-sqlite3` and `argon2`, so allow their install scripts (pnpm: `allowBuilds`).                                                                |
| TypeScript, optional                   | `moduleResolution` of `bundler`, `node16` or `nodenext`, so subpath exports resolve.                                                                                                                     |

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 [#install-from-npm]

      ### Install Better Compute and Better IAM [#install-better-compute-and-better-iam]

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install better-compute better-iam
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add better-compute better-iam
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add better-compute better-iam
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add better-compute better-iam
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    `better-compute` is the umbrella package: it depends on every `@better-compute/*` package in it and gives you the
    `better-compute` command. `better-iam` is Better IAM's umbrella package; it brings `@better-iam/server`,
    `@better-iam/core`, `@better-iam/adapter-sqlite` and the rest of Better IAM, which Better Compute declares as
    optional peers (`^0.2.0`; see [optional peers](#optional-peers)).
  
      ### Add PGlite for development [#add-pglite-for-development]

    PGlite is the development database, and `better-compute dev` uses it when there is no database URL. It is an
    optional peer, so npm does not install it for you:

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install @electric-sql/pglite
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add @electric-sql/pglite
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add @electric-sql/pglite
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add @electric-sql/pglite
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    A deployment that runs only against PostgreSQL does not need it.
  
      ### Check it [#check-it]

    ```bash
    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`):

```bash
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:

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

```bash
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](/docs/guides/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](/docs/operations/local-development)
covers the workspace scripts.

## Subpath imports [#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.

| Import                                              | Package                                          | What it provides                                                                                                                                                                                                |
| --------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `better-compute`                                    | `@better-compute/server`, `@better-compute/core` | `betterCompute`, `defineConfig`, `configOptions`, `ComputeError`, `defineModule`, `definePlugin`, `defineDriver`, `defineSchedulerPlugin`, `defineAttestor`, `defineSink`, `manifest`, `field`, and their types |
| `better-compute/core`                               | `@better-compute/core`                           | Browser-safe contracts: ids, errors, domain types, state tables, extension and port contracts, the IAM catalog, `defineMethod`                                                                                  |
| `better-compute/protocol`                           | `@better-compute/protocol`                       | Generated daemon and control-plane wire types                                                                                                                                                                   |
| `better-compute/inventory`                          | `@better-compute/inventory`                      | Section hashing, diffs, GPU model mapping, labels and health conditions                                                                                                                                         |
| `better-compute/capacity`                           | `@better-compute/capacity`                       | Atoms, bookings, quotas, rollups and the placement pipeline                                                                                                                                                     |
| `better-compute/provision`                          | `@better-compute/provision`                      | The workflow engine, `defineStep`, `defineProfile`, `provisionModule()`                                                                                                                                         |
| `better-compute/metal`                              | `@better-compute/metal`                          | Bare-metal verbs and drivers, `metal()`                                                                                                                                                                         |
| `better-compute/vps`                                | `@better-compute/vps`                            | Instances, runtimes, flavors, `defineProvider`, `vps()`                                                                                                                                                         |
| `better-compute/iam`, `/iam/plugin`, `/iam/testing` | `@better-compute/iam`                            | The Better IAM bridge, the plugin for IAM hosts, and an embedded Better IAM for tests and `dev --sim`                                                                                                           |
| `better-compute/events`                             | `@better-compute/events`                         | Signed webhooks and the server-sent `/watch` stream                                                                                                                                                             |
| `better-compute/fleet`                              | `@better-compute/fleet`                          | FleetConfig export, plan and apply                                                                                                                                                                              |
| `better-compute/rollout`                            | `@better-compute/rollout`                        | Signed bcd releases and wave rollouts                                                                                                                                                                           |
| `better-compute/audit`                              | `@better-compute/audit`                          | Signed per-tenant Merkle checkpoints over the audit log                                                                                                                                                         |
| `better-compute/observability`                      | `@better-compute/observability`                  | A bounded Prometheus registry and the standard metrics                                                                                                                                                          |
| `better-compute/server`                             | `@better-compute/server`                         | Everything the server exports: `betterCompute()`, the envelope, the registry, JoinService, controllers                                                                                                          |
| `better-compute/gateway`                            | `@better-compute/gateway`                        | Daemon sessions over gRPC on HTTP/2 mTLS, liveness and dispatch                                                                                                                                                 |
| `better-compute/pki`                                | `@better-compute/pki`                            | Local CAs, SPIFFE node certificates, sealed join tokens, attestors                                                                                                                                              |
| `better-compute/postgres`                           | `@better-compute/postgres`                       | `postgres({ url })`, migrations, `compute_now()` and sim-clock helpers                                                                                                                                          |
| `better-compute/pglite`                             | `@better-compute/postgres/pglite`                | `pglite()`, the development and test store                                                                                                                                                                      |
| `better-compute/client`                             | `@better-compute/client`                         | `createComputeClient`, the typed, browser-safe client                                                                                                                                                           |
| `better-compute/cli`                                | `@better-compute/cli`                            | The command line, also the umbrella's `better-compute` bin                                                                                                                                                      |
| `better-compute/mcp`                                | `@better-compute/mcp`                            | MCP tools for AI agents, gated by Better IAM                                                                                                                                                                    |
| `better-compute/testing`                            | `@better-compute/testing`                        | `computeFixture()`, `FakeDaemon`, the fleet simulator, the dev stack                                                                                                                                            |

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

## Built-in and injected modules [#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`:

```ts title="compute.ts"
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](/docs/extending/modules).

## Packages outside the umbrella [#packages-outside-the-umbrella]

These are installed directly, not through `better-compute`:

| Package                               | What it is                                                                                                                                                                                                     |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@better-compute/provider-hetzner`    | Hetzner Cloud servers as VPS instances and offers, and Hetzner Robot bootstrap                                                                                                                                 |
| `@better-compute/provider-proxmox`    | Proxmox VE QEMU VMs cloned from templates                                                                                                                                                                      |
| `@better-compute/provider-kubernetes` | Not a VPS provider: the manifests that run bcd as a DaemonSet on an existing cluster's nodes (`bcdDaemonSetManifests`, `renderKubernetesManifests`; 2c9f953). See [bcd on Kubernetes](/docs/daemon/kubernetes) |
| `@better-compute/driver-sdk`          | bcx, the out-of-process driver protocol (a v0.5 draft; the protocol is unstable until v0.5 ships)                                                                                                              |
| `@better-compute/console-kit`         | Framework-free view models for consoles over the typed client                                                                                                                                                  |

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

## Optional peers [#optional-peers]

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

| Peer                                                      | Needed for                                                                                                                                           |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@electric-sql/pglite` `^0.5.8`                           | `better-compute/pglite`, the testing fixture, `dev` without a database URL. Without it, the CLI fails with `MISSING_DEPENDENCY` and an install hint. |
| `@better-iam/server`, `@better-iam/core` `>=0.2.0 <0.4.0` | Embedded Better IAM through the bridge                                                                                                               |
| `@better-iam/adapter-sqlite` `>=0.2.0 <0.4.0`             | Better IAM on SQLite in development, and the embedded IAM of `dev --sim`                                                                             |
| `@better-iam/client` `>=0.2.0 <0.4.0`                     | `better-compute iam setup --meters`, which creates the billing meters in Better IAM                                                                  |
| `@better-iam/cli` `>=0.2.0 <0.4.0`                        | Declared for Better IAM's CLI; today the `better-compute` CLI reads its credential from `BETTER_COMPUTE_TOKEN` only                                  |

`@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](/docs/guides/iam) for how the
two products fit together.

## The daemon [#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](/docs/daemon/install#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](/docs/daemon/install).

## All packages [#all-packages]

## Verify the installation [#verify-the-installation]

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

```bash
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](/docs/reference/cli).

## Next steps [#next-steps]

  - [Quickstart](/docs/guides/quickstart): Run the development server with simulated GPU machines and reserve GPUs.

  - [Configuration](/docs/operations/configuration): Every `betterCompute()` option and the configuration file the CLI loads.

  - [Database](/docs/operations/database): PostgreSQL, PGlite, migrations and PgBouncer.