Deployment
Building
cargo build --release --no-default-features \
--features embedded,metal,local-embeddings,palace
Feature selection matters — omitting palace silently removes 7 MCP tools from
the running server.
| Feature | Effect |
|---|---|
embedded | In-process SurrealDB over SurrealKV |
server-only | External SurrealDB, no embedded engine |
local-embeddings | Candle-based local embedding |
metal / cuda | GPU backend (implies local-embeddings) |
palace | Memory Palace tools and 384d space |
On Apple Silicon, ./build.sh runs the quality gate then builds with Metal.
Quality gate
./scripts/quality-check.sh
Runs cargo fmt --check, cargo clippy -- -D warnings, and the test suite.
:::warning Test isolation
Run integration tests against a dedicated SurrealDB, not one shared with
live services. Sharing an instance makes tests compete with production traffic
for the same datastore, producing intermittent failures that look like code bugs.
Set TEST_SURREAL_ENDPOINT to a scratch server.
:::
Running as a service (launchd)
Two LaunchAgents run the stack on macOS. Both plists are rendered from
templates in prometheus-skill-pack (shared/launchagents/) by
scripts/prometheus-services.sh install; edit the templates, not the
rendered files, or the next install reverts your change.
| Label | Binary | Listens |
|---|---|---|
ai.prometheus.surrealdb-native | ~/.prometheus/bin/surreal (SurrealDB 4.0.0) | 127.0.0.1:28000 |
ai.prometheus.surreal-memory-native | /usr/local/bin/surreal-memory-server | 127.0.0.1:23001 |
The renderer refuses to write a surrealdb-native plist for any SurrealDB
version other than the certified one (SURREALDB_VERSION in the skill-pack's
config/defaults.env), so a stray Homebrew or PATH binary cannot downgrade
the database. The memory-server plist sets API_HOST=127.0.0.1: the REST/MCP
endpoints have no authentication in the default AUTH_MODE=local, which the
server refuses to run on any non-loopback bind. Shared deployments set
AUTH_MODE=jwt (see the configuration reference).
Points worth getting right:
ProcessTypemust beStandardfor both agents, neverBackground. launchd runs Background jobs at darwin background priority (scheduler priority 4, throttled disk and network I/O). On a loaded host that turned one-row SurrealDB queries into p99 6–15 s stalls and caused the 10 s operation-ledger timeouts in #36; at Standard the same queries take ~16–25 ms. Check withlaunchctl print gui/$(id -u)/<label> | grep "spawn type": it must not saybackground.KeepAliveplusThrottleIntervalso a crash loop does not hammer the host.MODEL_CACHE_DIRmust name the HuggingFace home;hubis appended when resolved.StandardErrorPath— the executor child inherits stderr, so its logs land in the same file.
Local deploy
# 1. Build from an up-to-date main
cargo build --release --features embedded,metal,local-embeddings,palace
# 2. Back up the installed binary, then install (keep both copies identical)
ts=$(date +%Y%m%d-%H%M%S)
cp -p /usr/local/bin/surreal-memory-server /usr/local/bin/surreal-memory-server.bak-$ts
install -m 755 target/release/surreal-memory-server /usr/local/bin/surreal-memory-server
install -m 755 target/release/surreal-memory-server ~/.local/bin/surreal-memory-server
# 3. Reload (bootout, bootstrap, enable, kickstart)
<skill-pack>/scripts/prometheus-services.sh load \
--exclude surrealdb-native --exclude pk-cherry --exclude forge-mcp --exclude prometheus-nudge
--exclude takes the label without the ai.prometheus. prefix. If
bootstrap fails with Input/output error right after a bootout, the old
process is still shutting down; wait for it to exit and bootstrap again.
Verify:
curl -s 127.0.0.1:28000/version # surrealdb-4.0.0
curl -s 127.0.0.1:23001/health # status ok
curl -s 127.0.0.1:23001/ready # every capability true
lsof -nP -iTCP:23001 -sTCP:LISTEN # bound to 127.0.0.1 only
The server handles SIGTERM, so a managed stop logs a clean shutdown rather
than dying silently.
Upgrading a running service
Migrations run automatically the first time a new binary starts, so a version bump can change your data's schema. A safe order:
- Export the databases (
surreal export, one per namespace and database) and keep the previous binary somewhere you can find it. - Build the new binary from a clean checkout of the commit you mean to run.
- Install it, then restart only the memory-server agent. The database agent does not need to restart.
- Read the startup log for
Applying migration …lines, then check/healthand/ready.
Migrations are additive, but they are not reversed by putting the old binary back. To return to the previous data, restore from the export.
Remember that a new default can change behavior on upgrade. Since AUTH_MODE was
introduced, the server refuses to start on a non-loopback API_HOST without
AUTH_MODE=jwt; see Authentication and tenancy.
Health and readiness
| Endpoint | Meaning |
|---|---|
GET /health | Liveness. Static; always 200 if the process serves. |
GET /ready | Readiness. 503 when the database handle is unavailable. |
/ready reports per-capability status — storage, ledger, model_executor,
search_index, tokenizer, coordinator. model_executor: false with
everything else true means the model has not loaded yet; search will fail until
it does.