Install

Nothing to install: the hosted tiers

Observe gives you an endpoint and a token from the portal; change your agent's base URL and the report appears as traffic flows. The trial, Solo and Starter tiers run the full kernel on your own database, hosted by us, with Gmail and IMAP connected from the console. Nothing of Razoo's runs on your machine and nothing needs updating.

Licensed tiers: two paths

Appliance, Appliance Plus and Enterprise run on your infrastructure from a packaged image under contract. Embed ships the SDK as a tarball under the Embed agreement. Neither contains source. Both need the tools below.

Prerequisites

No database server, no message broker, no model key. A missing key is a complete agent, not a trial.

Path A: the appliance, from the image

The appliance is a container image. Design partners receive it from us; there is no repository to clone and no source in the image. Mount a persistent volume for the SQLite file, give it a secrets key you own, and point it at your identity provider.

docker run -d --name razoo \
  -p 3000:3000 \
  -v razoo-data:/data \
  -e SQLITE_PATH=/data/engine.sqlite \
  -e ENGINE_SECRETS_KEY=<64 hex characters you generated> \
  -e AUTH_OIDC_ISSUER=<issuer> -e AUTH_OIDC_CLIENT_ID=<id> -e AUTH_OIDC_CLIENT_SECRET=<secret> -e AUTH_SECRET=<random> \
  <image you received>

The console listens on port 3000. The first boot creates the schema on the volume. Without ENGINE_SECRETS_KEY the appliance refuses to start in hosted mode; for a laptop, set ENGINE_AUTH=local and it keeps a sidecar key file next to the database instead (see Environment variables).

For volumes, backup and restore, see Appliance deployment.

Path B: the SDK, into your own product

1. Receive the tarball

The SDK is distributed to design partners as a tarball, engine-sdk-0.1.0.tgz, and is absent from the npm registry. You do not build it; we hand it to you with the licence.

The tarball contains compiled, minified JavaScript, a curated index.d.ts, LICENSE, and README. It does not contain source, tests, or source maps. Native and heavy dependencies (better-sqlite3, drizzle-orm, zod, js-yaml, imapflow, unpdf) stay external and install with it.

2. Install it in the host

cd /path/to/your-app
npm install /path/to/engine-sdk-0.1.0.tgz

cd /path/to/your-app
pnpm add /path/to/engine-sdk-0.1.0.tgz

The package name is @engine/sdk. Because it is ESM-only, the host must be an ESM project ("type": "module") or use a bundler that handles ESM dependencies. Next.js does.

3. Create an agent folder

Razoo reads agents from domains/<agent>/ under the root you pass to bootEngine. Copy the reference-brokerage folder from the agent kit that ships in the tarball and rename it, or author one from Authoring agents.

your-app/
  domains/
    my-agent/
      domain.yaml
      fields.yaml
      processes/
      rules/
      skills.yaml        # govern.propose overlay: which actions the SDK may stage
  data/
    engine.sqlite        # created on first boot

4. Boot once per process

import "server-only";
import path from "node:path";
import { bootEngine } from "@engine/sdk";

const root = process.cwd();
export const engine = bootEngine({
  root,
  sqlitePath: path.join(root, "data", "razoo.sqlite"),
});

bootEngine sets ENGINE_REPO_ROOT and SQLITE_PATH, runs migrations, registers the outbox handlers, and enables the drain. It must run before any other call from the package. It does not execute anything; confirmed actions still wait for a drain.

Next.js notes

• Import the boot module only from server code: Route Handlers, Server Actions, or server components. Mark it import "server-only" so a client import fails at build time.
• better-sqlite3 is native and will not run on the Edge runtime. Use the Node runtime for any route that touches Razoo (export const runtime = "nodejs").
• Keep the native module out of the bundle with serverExternalPackages (Next 15+; on Next 14 it is experimental.serverComponentsExternalPackages):

import type { NextConfig } from "next";

const config: NextConfig = {
  serverExternalPackages: ["better-sqlite3"],
};

export default config;

Verify with doctor

Doctor validates every agent folder and reports each problem as the file, what is wrong, and a valid example.

pnpm engine doctor                     # every agent under domains/
pnpm engine doctor domains/my-agent    # one agent, by path or by name

import { doctorAll, formatDoctor } from "@engine/sdk";

const report = doctorAll(process.cwd());
for (const r of report.reports) {
  if (r.issues.length) console.error(r.dir, formatDoctor(r.issues));
}
if (!report.ok) process.exit(1);

A green doctor prints the effective learnable field set per agent and the email connector state. email connector: not configured is informational; doctor stays green. The CLI exits 1 when any agent is not ok, so it is safe to put in CI.

Next: run the full loop.