VPS

Some of your capacity is best sold as whole machines, and some as virtual machines: a tenant wants a 2 vCPU box with an SSH key for a build agent, or an 8 vCPU VM with one L40S passed through, without renting a whole server. Other times you want to burst onto a cloud you do not run, and still keep one API, one quota system and one audit trail.

The vps() module does both. It adds instances: VMs described by a flavor, an image and SSH keys, created in a pool. Where the VM runs depends on the pool:

• A hosted pool runs VMs on your own servers. Capacity places each instance on a host, and the host's bcd converges it.
• A provider pool creates each instance on an external cloud, through a provider such as Hetzner Cloud or your own Proxmox VE cluster.

Either way, the API only records what you want. A reconciler does the work, and nothing in a request ever calls a hypervisor or a cloud API.

Register the module

vps() is an injected module: the server never imports it, so you add it to modules. It requires the built-in capacity module, which every server has.

import { betterCompute } from 'better-compute/server';
import { vps } from 'better-compute/vps';
import { hetznerCloud } from '@better-compute/provider-hetzner';
import { images } from './images';

export const compute = betterCompute({
  // database, secret, iam, …
  modules: [
    vps({
      runtimes: ['libvirt-kvm'], // hosted pools: the runtime driver bcd uses
      providers: [hetznerCloud], // provider pools: the providers accounts may use
      images, // hosted pools: resolves imageId for a tenant
    }),
  ],
});

The provider packages are on npm but sit outside the better-compute umbrella, so you install and import them by their own names (npm install @better-compute/provider-hetzner).

vps ships no image resolver: Better Compute checks image visibility itself, and you decide where images come from. This one serves hosted VMs the images registered through the images group of provisionModule, when the tenant owns them or they are public:

import type { ImageResolver } from '@better-compute/vps';

export const images: ImageResolver = {
  async resolve(tx, tenantId, imageId) {
    const { rows } = await tx.query<{
      source: string;
      sha256: string;
      format: 'raw' | 'qcow2' | 'iso';
      verified: boolean;
    }>(
      `SELECT source, sha256, format, verified FROM images
        WHERE id = $1 AND deleted_at IS NULL AND (tenant_id = $2 OR visibility = 'public')`,
      [imageId, tenantId],
    );
    const image = rows[0];
    // undefined: the tenant cannot see it, and instances.create answers NOT_FOUND.
    return image && { url: image.source, sha256: image.sha256, format: image.format, verified: image.verified };
  },
};

verified becomes the instance's imageVerified attribute, which policies can require.

Registering the module adds:

• the instances, flavors and providerAccounts API groups (instances, flavors, providerAccounts), and the v0.5 sandboxes, sandboxTemplates and sandboxSnapshots groups (sandboxes, sandboxTemplates, sandboxSnapshots) for sandboxes on hosted pools;
• the migrations vps/0001_instances, with the tables flavors, provider_accounts, instances, ip_pools and ip_leases, vps/0002_sealed_user_data (instances.user_data_sealed), vps/0003_provider_bootstraps (provider_bootstraps, for bootstrapping provider machines) and, for sandboxes, vps/0004_sandboxes (the tables sandbox_templates and sandboxes, the columns instances.sandbox_id and instances.warm_template_id, and paused as a desired state), vps/0005_sandbox_snapshots (sandbox_snapshots, instances.restore_from, sandboxes.from_snapshot), vps/0006_warm_claims (instances.claimed_at), vps/0007_template_env (sandbox_templates.env) and vps/0008_template_network (sandbox_templates.network and instance_version, instances.network_policy and warm_template_version), vps/0009_snapshot_fixes (sandbox_snapshots.principal_instance_id and purged), vps/0010_sandbox_metric_indexes (partial indexes for the sandbox metrics), vps/0011_host_certificates (instances.host_certified, sandbox_snapshots.host_certified) and vps/0012_host_cert_validity (host_cert_valid_before on both);
• the vps.instances reconciler, woken through the work queue by every change, the vps.sandboxes reconciler (every 15 seconds: sandbox expiry, sandbox events, warm pools and settling snapshots), and the vps.usage job, which meters hosted instances every 5 minutes;
• the instance.snapshot command kind (lane bulk, timeout 1 h) for sandbox snapshots;
• a tenantDeleted hook that deletes every instance of a deleted IAM tenant, sandboxes' and warm ones included;
• an instances section in the NodeSpec of each hosted node;
• the runtime driver kind, merged into DriverKinds of @better-compute/core when you import the package;
• doctor findings for hosted pools: vps.pools.runtime (a runtime the deployment does not list), vps.pools.single-tenant (a container pool without policy.singleTenant), vps.pools.ipam (no IP range) and vps.hosts.capacity (adopted hosts without capacity rows); see doctor.

Hosted pools also need the gateway to feed each host's runtime report to vps. Pass instanceStatusHandler as a status handler. It runs next to the built-in XID health handler, each under its own savepoint:

import { defineHost } from '@better-compute/cli';
import { instanceStatusHandler } from '@better-compute/vps';

export const host = defineHost(async ({ compute }) => ({
  gateway: {
    // region, listen, tls, …
    options: { reports: { status: instanceStatusHandler({ events: compute.context.events }) } },
  },
}));

Hosted pools and provider pools

A VPS pool is a pool of class vps-host or provider, created with pools.create like any other. Instances in pools of other classes are refused with INVALID_INPUT.

No platform agent ever runs inside a tenant VM, and no join token ever goes into tenant-readable user data. A provider machine that should become a host of your own (a Hetzner Robot server that runs bcd) is a different thing: see bare metal.

The instance model

An instance has two states. desiredState is what you asked for: running, stopped or deleted. state is where the instance actually is. instances.create sets desiredState (default running); start, stop and delete change only desiredState and wake the reconciler. The reconciler moves state toward it, one guarded transition at a time, from what the host or the provider reports.

Every state except deleted and deleting can move to deleting, and most can move to error and lost. The full table is instanceStateTable in @better-compute/core; since 564f543 it also allows recreate from provisioning and stopped, for an instance whose host cannot start it (see hosts that cannot start an instance). rebooting is in the table, but no API method enters it in this release. paused (v0.5: running to paused by pause, back by resume) is used only by the warm pools of sandboxes; see paused instances.

The API returns the Instance view:

Instances covers each operation and how the reconciler turns reports into transitions.

What ships in v0.3

The control plane is complete and tested: the three API groups, admission, the reconciler for both pool kinds, pool IPAM, the report seam and metering run against PGlite in tests/vps-instances.test.ts, and tests/vps-churn.test.ts runs the v0.3 acceptance shape (200 instances churned on 3 emulated hosts with no leaked allocation, IP lease, scalar claim or quota). What runs the VMs on a host is written but not yet proven: bcd's libvirt-kvm and cloud-hypervisor runtimes have been tested against fake tools only.

The TypeScript FakeDaemon in @better-compute/testing speaks the real protocol for the simulator and better-compute dev --sim N. As a VPS host it runs a FakeHypervisor (domains, overlays, NoCloud seeds, pause and resume), which is how tests/e2e/vps.test.ts runs hosted instances through the real server and gateway. The unit suites, tests/vps-sandboxes.test.ts among them, emulate hosts by calling reportInstances directly.