Skip to main content

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.

FeatureEffect
embeddedIn-process SurrealDB over SurrealKV
server-onlyExternal SurrealDB, no embedded engine
local-embeddingsCandle-based local embedding
metal / cudaGPU backend (implies local-embeddings)
palaceMemory 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.

LabelBinaryListens
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-server127.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:

  • ProcessType must be Standard for both agents, never Background. 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 with launchctl print gui/$(id -u)/<label> | grep "spawn type": it must not say background.
  • KeepAlive plus ThrottleInterval so a crash loop does not hammer the host.
  • MODEL_CACHE_DIR must name the HuggingFace home; hub is 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:

  1. Export the databases (surreal export, one per namespace and database) and keep the previous binary somewhere you can find it.
  2. Build the new binary from a clean checkout of the commit you mean to run.
  3. Install it, then restart only the memory-server agent. The database agent does not need to restart.
  4. Read the startup log for Applying migration … lines, then check /health and /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​

EndpointMeaning
GET /healthLiveness. Static; always 200 if the process serves.
GET /readyReadiness. 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.