Compute Agent and CLI

The node agent deploys on a compute; tenant mode also holds one complete project across environments in RAM and serves it over a group-scoped unix socket, while platform mode never duplicates the API vault.

Package overview

Every managed compute. It owns node identity, attestation and repository pipelines. An SNP compute may hold its assigned whole project across environments in RAM after current attestation. Ordinary compute is API-only unless an administrator explicitly records the versioned non-TEE risk acceptance for that concrete machine. Platform mode never replicates realm-wide API authority beside the process that already holds unlocked realm seeds. Supported runtimes: bun, node. Package root: @forgezero/agent. Consumer documentation is curated with each module's explicit public flag; the complete internal/export inventory remains in the typed SSOT and declaration files.

bun add -g @forgezero/agent

ForgeZero package family

The five packages are installation boundaries. Choose a package by who installs it; choose a subpath by the capability used in that file.

| package | short description | runtimes | documentation | |---|---|---|---| | @forgezero/vault | Scoped secret access with Agent, API-key and systemd-credential sources. | bun, node, workers, deno | Open | | @forgezero/access | Typed route, principal, factor, RBAC and request-pipeline contracts. | bun, node, workers, deno | Open | | @forgezero/providers | Typed external providers with priority, health and classified fallback. | bun, node, workers, deno | Open | | @forgezero/runtime | Portable runtime primitives for queries, jobs, events, schemas and finance. | bun, node | Open | | @forgezero/agent | Operator CLI and managed-node agent for bootstrap, deploy and lifecycle. | bun, node | Open |

@forgezero/agent supported imports and commands

These are supported consumer entry points, not every internal module shipped for ForgeZero managed installation. Each row links to its task-oriented usage.

| public entry | short description | runtime | details | |---|---|---|---| | @forgezero/agent/deploy | Typed deployment authoring builders, built-in provider requirements and versioned action constructors. | Bun/Node host | Reference + usage | | @forgezero/agent/schema/deploy-v3.json | Published JSON Schema for deployment definition version 3 with exact argv execution. | Bun/Node host | Reference + usage |

Commands

bun add -g @forgezero/agent — Install the version-matched fz operator CLI and fz-agent daemon. fz deploy init — Create a typed forgezero.deploy.ts and its canonical inert execution plan. fz deploy compile — Compile and validate TypeScript deployment intent into .fz/deploy.plan.json. fz deploy check — Refuse stale plans, unsafe provider/action coordinates and unresolved deployment blockers.

bun add -g @forgezero/agent
fz deploy init
fz deploy compile
fz deploy check

@forgezero/agent/deploy

Typed deployment authoring builders, built-in provider requirements and versioned action constructors. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  actions,
} from '@forgezero/agent/deploy';

@forgezero/agent/deploy — Author a typed, placed containerd deployment

TypeScript is authoring only. The checked-in canonical plan is what Agents validate and execute. Targets declare bounded resource/cardinality intent, not hostnames. The API reserves eligible project capacity or provisions only under the reviewed plan and spend ceiling, assigns stable slots, and the Agent runs only its exact assignment. An optional per-metal topology elects one active relay and one standby without naming computes: one or two Metals use proven private relay links and never install WARP, while three or more give Mesh/WARP authority only to relay and standby. runc containers must declare hard CPU, memory and PID limits, bounded storage, loopback ingress and a health-gated rollout; select Kata QEMU SNP when the workload needs host isolation.

import {
  actions,
	  application,
	  credential,
	  defineDeployment,
	  input,
	  providers,
	  ref,
  stage,
  target,
  workflow,
} from '@forgezero/agent/deploy';

export default defineDeployment({
  apiVersion: 'deploy.forgezero.net/v1', kind: 'Deployment',
  metadata: { name: 'orders-api' },
  spec: {
	inputs: {
	  replicas: input.integer({ minimum: 1, maximum: 16, default: 1 }),
	  cpuCores: input.integer({ minimum: 1, maximum: 32, default: 1 }),
	  memoryMiB: input.integer({ minimum: 256, maximum: 131072, default: 512 }),
	  storageGiB: input.integer({ minimum: 4, maximum: 2048, default: 8 })
	},
	credentials: {
	  cloudflare: credential.vault({ schema: 'forgezero.cloudflare/management@1', name: 'cloudflare-management' })
	},
	targets: { api: target.compute({
	  profiles: ['api'], replicas: { minimum: 1, desired: input.ref('replicas'), maximum: 16 },
	  resources: { cpuCores: input.ref('cpuCores'), memoryMiB: input.ref('memoryMiB'), storageGiB: input.ref('storageGiB') },
	  os: 'ubuntu-24.04', runtime: 'oci-runc', sharing: 'shared', reuse: 'prefer',
	  provisioning: {
	    regionKey: 'default', imageKey: 'ubuntu-24.04-x64', environmentKey: 'production', ownership: 'platform',
	    resources: {
	      physicalCores: 1, vcpu: 2, memoryGib: 2, diskGib: 16,
	      egressGuaranteedMbps: 100, egressBurstMbps: 200, confidential: false
	    },
	    monthlyAmountCents: '1200', maxMonthlySpendMinor: '25000'
	  },
	  connectivity: {
	    private: { mode: 'private-lan' },
	    public: { mode: 'cloudflare-tunnel', credential: 'cloudflare', zone: 'example.com', hostname: { mode: 'indexed', prefix: 'api' } }
	  },
	  topology: {
	    groupBy: 'metal',
	    relays: {
	      activePerMetal: 1,
	      standbyPerMetal: 1,
	      healthPort: 3000,
	      routedTcpPorts: [3000]
	    },
	    crossMetal: {
	      mode: 'auto',
	      directPrivateMaximumMetals: 2,
	      credential: 'cloudflare',
	      network: 'orders-api'
	    }
	  },
	  placement: { spreadBy: ['metal'], antiAffinity: ['orders-api'] }
	}) },
	requirements: {
	  containerd: providers.containerd.require(), nginx: providers.nginx.require(),
	  cloudflared: providers.cloudflared.require()
	},
    components: {
      api: application({
        target: 'api',
		runtime: { kind: 'container', provider: 'forgezero.containerd', requirement: 'containerd', runtimeClass: 'runc', image: { source: { kind: 'build', context: '.', dockerfile: 'Dockerfile' } }, security: { privileged: false, noNewPrivileges: true, root: 'read-only', dropCapabilities: ['ALL'] } },
        service: { protocol: 'http', port: 3000, health: { protocol: 'http', method: 'GET', path: '/health', expectedStatus: [200], timeoutMs: 2000 } },
		resources: { cpu: { limit: 1 }, memory: { limitMiB: 512, swap: 'disabled' }, pids: { limit: 256 } },
        storage: [{ class: 'ephemeral', path: '/tmp', type: 'tmpfs', sizeMiB: 128 }],
	        network: {
	          ingress: { exposure: 'public', stablePort: 3000 },
	          public: { mode: 'cloudflare-tunnel' },
	          container: { mode: 'bridge', network: 'api' }
	        },
        rollout: { strategy: 'blue-green', proxy: 'nginx', automaticRollback: true }
      })
    },
	workflows: { deploy: workflow({ stages: {
	  prepare: stage({ strategy: { mode: 'sequential' }, steps: {
		    software: actions.software.ensure({ requirements: ['containerd', 'nginx', 'cloudflared'] }, { scope: { kind: 'each-target', target: 'api' } }),
		    network: actions.network.ensure({ target: 'api' }, { scope: { kind: 'each-target', target: 'api' } }),
		    image: actions.container.build({ component: 'api' }, { scope: { kind: 'each-target', target: 'api' } })
	  } }),
	  release: stage({ dependsOn: ['prepare'], strategy: { mode: 'blue-green' }, steps: {
	    promote: actions.service.promote({ component: 'api', imageDigest: ref.stepOutput('image', 'digest') }, { scope: { kind: 'each-target', target: 'api' } })
	  } })
	} }) }
  }
});

@forgezero/agent/schema/deploy-v3.json

Published JSON Schema for deployment definition version 3 with exact argv execution. This entry is JSON data rather than a JavaScript namespace.

import schema from '@forgezero/agent/schema/deploy-v3.json' with { type: 'json' };

@forgezero/agent/schema/deploy-v3.json — Validate a deployment definition against the published schema

Definition version 3 rejects unknown fields and shell command strings; every step is a bounded exact argv vector. Credentials remain named references resolved by Vault or the same-named encrypted systemd fallback.

import deploySchema from '@forgezero/agent/schema/deploy-v3.json' with { type: 'json' };
import Ajv from 'ajv';

const validate = new Ajv({ allErrors: true, strict: true }).compile(deploySchema);
if (!validate(deploymentDefinition)) throw new Error(JSON.stringify(validate.errors));

Install both machine commands

One public package installs fz and fz-agent at the same version. fz breaks the bootstrap circle from an operator machine; fz-agent runs managed work. Keeping them together prevents a new bootstrap command from provisioning an old daemon protocol.

bun add -g @forgezero/agent
fz --help
fz-agent --help

One project memory for every AI tool

Conversation memory and dated audits are observations, not architecture. fz project init creates one strict, vendor-neutral manifest in Git; sync renders only the thin discovery files Claude, Codex, Gemini, Copilot and Cursor expect, and check fails if a named truth source disappeared or an adapter was edited independently. Teams can switch tools without restating the project and without maintaining five competing plans.

fz project init          # creates .forgezero/project.json
# edit the manifest and its named truth sources
fz project sync          # generate vendor adapters
fz project check         # CI/handoff drift gate

Genesis is browser-first; recovery can remain headless

The CLI starts device authorization before the founder exists and opens the one-use invitation created by fz bootstrap platform. The browser creates the account, registers and freshly proves its passkey, confirms the account recovery phrase, then explicitly approves the displayed terminal code and continues to custody. The CLI receives only a bounded session. Custody phrases and passkey PRF output remain in the browser. After restart, each participating custodian opens only their own phrase envelope using an owner-only phrase file or stdin and contributes the share from their own authenticated, freshly proved session. No CLI process collects several custodians’ phrases. SSH remains transport and Git interoperability only; it is not a ForgeZero authentication or custody factor. Neither path creates a privileged server bypass.

fz genesis --mode 1-of-1
fz status
fz unlock --phrase-file /secure/offline-phrase.txt

Use website operations from a project or an AI agent

Every UI operation is an API operation. fz ui routes --json discovers the exact actions allowed by the signed-in account’s current realm, lifecycle stage and grants from the API’s enforced matrix, so the CLI and AI agents carry no copied route list. fz api (also fz ui) executes authenticated JSON GET, POST, PUT, PATCH and DELETE without requiring a browser visit for ordinary work. Paths are forced onto the signed-in origin, query values are repeatable, bodies can be inline, stdin or a file, and server grants plus fresh-proof rules remain authoritative. fz project init|sync|check separately gives AI tools one Git-persisted project memory.

fz ui routes --json
fz ui routes pipeline
fz ui get /workspace/pipelines --query projectKey=my-project
fz api post /workspace/pipelines/status --data '{"pipelineKey":"pl_…","enabled":false}'
generate-request | fz api post /workspace/action --data -

What changes for an application

Nothing. With no agent, this needs FORGEZERO_API_KEY in the environment. With the agent, it does not — and the key that would have been on the box does not exist. @forgezero/vault prefers the socket automatically.

import {
  ForgeZero,
} from '@forgezero/vault';

const fz = new ForgeZero({ project: 'payments-api', environment: 'production' });
await fz.get('PAYMENT_PROVIDER');

A local copy, not a cache

The agent holds the whole assigned project across all of its environments, not just what has already been read. Each application still supplies its environment and cannot cross the enrolled project boundary. That is the difference between surviving an outage and not: a read-through cache lacks the never-before-read value precisely when the platform is unreachable. The cost is that a compromised guest exposes everything in the enrolled project rather than only what was read — bounded by the project and by SEV-SNP keeping the host out of guest memory.

Local access is explicit Unix membership

The socket is mode 0660 in the dedicated forgezero-vault group. A service account must be deliberately added to that group before it can read the project replica; unrelated local users and the credential-free deployment runner cannot connect. Mode 0600 would make the advertised app integration unusable, while a world-readable socket would hand the vault to every process on the guest.

Never on disk

A cache file would hand an attacker with filesystem access every secret this guest has ever held, which is precisely the artefact this design exists to remove. A restart re-fetches. There is no version of "just persist it, it is encrypted" that survives the key also being on the box.

Invalidated by cursor, and refused when stale

A TTL alone means a rotated secret keeps working for the length of the TTL — the window rotation exists to close. The agent polls a change cursor and drops what moved, so a rotation propagates regardless of TTL. And if sync has not succeeded within the staleness bound, a read is refused rather than served: an application that receives a revoked credential and succeeds with it is worse off than one that receives an error, because the error is visible.

Two postures, decided by the hardware

An SNP guest can produce an attestation report and the platform can refuse a node whose measurement is wrong. Anything else authenticates with its enrolment token and a hybrid Ed25519 + ML-DSA-65 signature. Both are real: enrolled is still strictly better than an API key in the application, because the key never leaves the agent, rotation reaches every process, and the socket is filesystem-scoped.

attested   /dev/sev-guest present  -> hardware report
enrolled   no SNP device           -> enrolment token + hybrid signature

The app socket cannot impersonate the node

The group-scoped application socket exposes only replica get, held and sync operations. Node identity, hybrid signing and attestation stay inside the Agent's outbound clients. Every Agent call requires HTTPS outside loopback, signs a one-use hybrid ML-KEM-768 + X25519 recipient and refuses a successful response that is not sealed back to that request. A process allowed to read one environment therefore cannot ask the Agent to sign a deployment, heartbeat or whole-project replication request and act as the node.

get        one secret in the selected environment
sync       invalidate rotated values
held       names held in the selected environment

identity/sign/attest   refused on the application socket

Full rendered documentation: https://www.forgezero.net/docs/agent