Operate

Self-hosting

Run your own relay against your own Postgres + GCP project. The CLI just points at a different URL.

The relay is one Rust binary backed by Postgres. Everything that makes aiperson useful is local — ~/.dotperson/corpus.db (events + threads + messages) plus your persona repo — so the relay’s job is narrow: GitHub App brokerage, Firebase auth, synthesis, and cross-device sync. The local-first daemon (personkit daemon --install) works without any relay at all if you don’t need cross-device sync.

Requirements

Postgres 14+
Firebase project (Auth + Hosting if you want the dashboard)
A GCP project for Vertex AI (optional — synthesis degrades to no-op)
A GitHub App (optional — PAT path works without)

Build

cd engineering/personkit
cargo build --release -p memory-layer-relay

The binary is at engineering/personkit/target/release/memory-layer-relay.

Configure

Variable	Default	Notes
`PORT`	`8080`	HTTP listen port
`DATABASE_URL`	(unset)	Postgres DSN
`FIREBASE_PROJECT_ID`	`dotperson-pbc`	Token `aud` + `iss`
`GCP_PROJECT_ID`	`dotperson-pbc`	Secret Manager parent
`GITHUB_APP_ID`	(unset)	Numeric App ID
`GITHUB_APP_SLUG`	`aiperson`	Install link slug
`PERSONKIT_RUN_MIGRATIONS`	(unset)	Set `1` only on a fresh DB or after seeding `_sqlx_migrations`
`PERSONKIT_SYNTHESIS_INTERVAL_SECS`	`60`	Worker tick
`PERSONKIT_SYNTHESIS_CONFIDENCE_THRESHOLD`	`0.85`	Floor for persona mutation
`LOG_FORMAT`	(unset)	Set `json` for structured logs

Migrate

The relay’s migrations are additive only (Atlas Prime Directive by analogy). Apply manually on first boot if your DB pre-dates the _sqlx_migrations ledger, or set PERSONKIT_RUN_MIGRATIONS=1 on a fresh DB.

sqlx migrate run --source engineering/personkit/crates/memory-layer-relay/migrations

Point the CLI

Pass your relay URL to setup (or login) with --relay. It’s persisted into ~/.dotperson/credentials.json (relay_url) and every later command reads it from there — there is no relay env var to export.

personkit setup --relay https://your-relay.example.com
personkit daemon --install

The daemon reads the stored relay_url from your credentials on each cycle, so its harvest → embed → observe → sync loop talks to your relay automatically. (The launchd plist itself only exports HOME and PATH.) To switch relays later, re-run personkit login --relay https://new-relay.example.com — the next daemon cycle picks up the new URL.

Pure local mode

If you don’t want a relay at all:

personkit daemon --install   # local-first cycle: harvest + embed + synthesise

Without personkit login ever being run, the observe and sync stages of the daemon early-return (no credentials → no POST). Harvesters, the embedder, the synthesis pass, and the daily brief still work — your corpus stays useful, just not cross-device.