Configuration

A deployment is configured in one TypeScript or JavaScript module that every process loads. Its default export holds the options of betterCompute(); its named host export holds what better-compute serve runs around the control plane. Values that differ between environments come from environment variables.

The configuration file

The CLI looks for the configuration in this order:

1. --config PATH;
2. BETTER_COMPUTE_CONFIG;
3. the nearest better-compute.config.mjs, .js, .ts or .mts, in the working directory and then each parent.

With no file, BETTER_COMPUTE_DATABASE_URL and BETTER_COMPUTE_SECRET describe a minimal deployment on their own (configFromEnv): the store from the URL, BETTER_COMPUTE_BASE_URL (default http://localhost:3000), root tenant root, and no IAM, so only public methods answer. A .ts configuration needs Node.js 22.18 or newer, which strips types by default. better-compute init writes a starter file and never overwrites one.

The module is executable code and is trusted as such. It can export four things:

Prefer the factory form. Importing the module then opens nothing; the CLI calls the factory with { command, env, cwd }, and your own server calls it through configOptions(config):

import { postgres } from 'better-compute/postgres';
import { pglite } from 'better-compute/pglite';
import { defineConfig } from 'better-compute/server';

export default defineConfig(({ env = process.env, cwd = process.cwd() } = {}) => ({
  database: env.BETTER_COMPUTE_DATABASE_URL
    ? postgres({ url: env.BETTER_COMPUTE_DATABASE_URL })
    : pglite({ dataDir: `${cwd}/.better-compute-pglite` }),
  secret: env.BETTER_COMPUTE_SECRET ?? '',
  baseURL: env.BETTER_COMPUTE_BASE_URL ?? 'http://localhost:3000',
  rootTenantId,
  iam: bridge.embedded(iam, { rootTenantId }),
  modules: [...bridge.modules /* , metal(), vps(), … */],
}));

import config from './better-compute.config';
import { betterCompute, configOptions } from 'better-compute/server';

const compute = betterCompute(await configOptions(config));

betterCompute() options

betterCompute() is synchronous and side-effect free: it validates the options and registers the method table. Anything wrong throws INVALID_CONFIG before a connection is opened.

Required

Optional

capacity

worker

These are fixed: shard and singleton leases live 15 s and renew every 5 s, a worker is live while its heartbeat is younger than 30 s, SYNC_AGAIN brings a key back after 1 s, failures back off from 1 s to 5 minutes, and the CommandSweeper runs every 5 s.

pki

The PKI bundle supplies all of these:

import { loadPkiBundle } from 'better-compute/cli';
import { pkiJoinCrypto } from 'better-compute/server';

const bundle = await loadPkiBundle('.better-compute/pki.json', env); // unsealed with BETTER_COMPUTE_SECRET
const pki = {
  nodeCa: bundle.nodeCa,
  join: pkiJoinCrypto({
    trustDomain: bundle.trustDomain,
    nodeCa: bundle.nodeCa,
    signingKey: bundle.joinSigning,
    encryptionKey: bundle.joinEncryption.privateKey,
  }),
  commandSigning: bundle.commandSigning,
};

See PKI.

tunnels

The api role mounts the tunnel upgrade only when tunnels.issuer is set, and it needs a re-authorizer: an IamPort with authorizeSession (the IAM bridge has one) or host.tunnels.authorize. See tunnels.

The host export

host is what serve runs around the control plane. A factory receives { compute, options, env, cwd }, so routes can close over the same instances the modules use.

import { readFile } from 'node:fs/promises';
import { defineHost } from 'better-compute/cli';
import { handleWatch } from 'better-compute/events';
import { createMetrics } from 'better-compute/observability';

const metrics = createMetrics();

export const host = defineHost(async ({ compute, env }) => ({
  http: { routes: [{ path: '/watch', method: 'GET', handler: (request) => handleWatch(request, { sql: compute.context.sql, authorize }) }] },
  metrics: { registry: metrics, bearerToken: env.BETTER_COMPUTE_METRICS_TOKEN },
  gateway: {
    region: 'eu-1',
    listen: { port: 8443 },
    tls: {
      key: await readFile('.better-compute/gateway/gateway.key', 'utf8'),
      cert: await readFile('.better-compute/gateway/gateway.crt', 'utf8'),
      ca: bundle.nodeCa.export().certificatesPem,
    },
    internal: { url: 'https://gw-1.internal:8444', tls: internalServerTls },
  },
}));

serve checks the shape and refuses a bad one with INVALID_CONFIG; doctor checks the wiring.

Modules and their options

Modules are values you construct and pass in modules, each with options of its own. The examples register:

const bareMetal = metal({ hardwareProfiles });
modules: [
  provisionModule({ modules: [bareMetal] }), // runs metal's workflows
  bareMetal,
  vps(),
  retentionModule(), // added by the CLI when missing
  eventsModule({ secret }), // seals webhook signing secrets under the deployment secret
  fleetModule(),
  rolloutModule({ release: { pins }, downloadsUrl }), // needs the release keys' pins
  auditModule({ signer: bundle.auditSigning }), // needs the bundle's audit key
];

Each module's own migrations run with better-compute migrate (see database). Its options are documented with the module; see modules.

Environment variables

The CLI reads these:

Inside the configuration, variables are yours to name: the file reads env and decides. The CLI only guarantees that env is the process environment.

The deployment secret

secret is at least 32 random characters, identical in every process of the deployment. Generate it once:

openssl rand -base64 48

It protects:

• Secrets at rest. Without secrets, sealed_secrets holds values sealed with AES-256-GCM under a key derived from it (migration pki/0001_sealed_secrets).
• The PKI bundle. pki init seals the private keys under a key derived from BETTER_COMPUTE_SECRET (HKDF-SHA256, AES-256-GCM); every process unseals the bundle with it.
• Webhook signing secrets, when you pass it to eventsModule({ secret }) as the examples do.