Installation

Prerequisites, Docker Compose for Postgres, and environment variables for running Yoke locally.

Yoke is a Rust crate you embed in your server. It boots an in-process Deno worker for your internal TypeScript package and uses Postgres as the durable runtime store. This page covers what the host machine needs.

The yoke CLI is the same kernel, packaged as an authoring tool so you can load a package without writing a host first. See Embed Yoke in your product.

Prerequisites

Requirement	Version	Notes
Rust	stable	Build tooling for compile output and embed workflows
Deno	2.x	Used by the embedded worker for TypeScript transpilation and npm/jsr resolution
Postgres	16+	Compulsory runtime storage — stream, instances, queues
yoke CLI	latest	Authoring commands (`yoke dev`, `yoke compile`, `yoke append`)

Postgres is required. There is no single-node mode without a database. Actor SQLite state is stored either in Postgres (pg_sqlite) or S3 (s3), not as standalone local files you manage directly.

Start Postgres with Docker Compose

Use Docker Compose (or any Postgres 16+ instance) for local development:

docker compose up -d

Default connection string:

export DATABASE_URL=postgres://yoke:yoke@localhost:5432/yoke

For local single-tenant development you only need Postgres. Multi-tenant deployments add a control plane service on port 8090.

Install the yoke CLI

Install the yoke CLI for your platform, then verify:

yoke --help

During development you can also build the CLI from source if you are working on the runtime itself.

Required environment variables

Variable	Required	Default	Purpose
`DATABASE_URL`	Yes	—	Postgres connection string
`YOKE_STORAGE`	Yes	`pg_sqlite`	Actor SQLite backend: `pg_sqlite` or `s3`
`YOKE_PORT`	No	`8080`	HTTP port for portal routes, `/health`, `/metrics`
`YOKE_DATA_DIR`	No	`.yoke-data`	Local cache directory (S3 mode, worker metadata)
`YOKE_TENANT_ID`	No	`default`	Tenant id for row isolation

Minimal local setup:

export DATABASE_URL=postgres://yoke:yoke@localhost:5432/yoke
export YOKE_STORAGE=pg_sqlite

CLI flags

The yoke dev command accepts the same settings as environment variables:

yoke dev ./your-package \
  --database "$DATABASE_URL" \
  --storage pg_sqlite \
  --port 8080 \
  --data-dir .yoke-data \
  --tenant-id default

Run migrations explicitly if needed:

yoke migrate --database "$DATABASE_URL"

yoke dev runs migrations automatically on boot.

User package dependencies

Your package needs a deno.json with an import map to @yoke/sdk:

{
  "name": "your-package",
  "imports": {
    "@yoke/sdk": "jsr:@yoke/sdk@^0.1.0",
    "zod": "npm:zod@^4.5.4"
  }
}

Import @yoke/sdk from JSR in published packages. During local development you may use a path import if you are co-developing the SDK.

Verify the install

Confirm Postgres is reachable:

psql "$DATABASE_URL" -c 'SELECT 1'

Build and start the runtime (see Quick start):

yoke dev ./your-package \
  --database "$DATABASE_URL" \
  --storage pg_sqlite

Hit the health endpoint on the portal HTTP port:

curl http://localhost:8080/health

pg_sqlite stores serialized SQLite files in the Postgres actor_sqlite table as BYTEA blobs — it is not a Postgres extension. Both stream metadata and actor state share the same database connection in this mode.