Bare metal

You can run Spectron directly on a Linux host as a systemd service. This is appropriate for single-server deployments, edge environments, or situations where container runtimes are not available.

Prerequisites

• A Linux host with systemd (Debian, Ubuntu, RHEL, Fedora, or equivalent)

• A running SurrealDB instance (local or remote)

• An object store endpoint (S3-compatible, GCS, or a local filesystem path)

• curl for downloading the binary

Obtaining spectrond

Self-hosted Spectron is distributed as the container image ghcr.io/surrealdb/spectron:latest. For bare-metal hosts without Docker at runtime, extract the server binary from the image:

docker pull ghcr.io/surrealdb/spectron:latest
docker create --name spectron-extract ghcr.io/surrealdb/spectron:latest
docker cp spectron-extract:/usr/local/bin/spectrond /usr/local/bin/spectrond
docker rm spectron-extract
chmod +x /usr/local/bin/spectrond

Install the spectron client separately if operators need CLI access (same image, or your organisation’s client distribution channel).

Verify:

spectrond --version

Creating a dedicated user

Run Spectron as a dedicated non-root user:

useradd --system --no-create-home --shell /sbin/nologin spectron

Create the data directory for local object storage (skip if using S3 or GCS):

mkdir -p /var/lib/docs/spectron/objects
chown spectron:spectron /var/lib/docs/spectron/objects

Environment file

Create an environment file at /etc/docs/spectron/env. Restrict its permissions so that only root and the spectron user can read it:

mkdir -p /etc/spectron
touch /etc/docs/spectron/env
chmod 640 /etc/docs/spectron/env
chown root:spectron /etc/docs/spectron/env

Populate it:

# /etc/docs/spectron/env

SPECTRON_SURREALDB_URL=ws://127.0.0.1:8000
SPECTRON_OBJECT_STORE_URL=file:///var/lib/docs/spectron/objects
SPECTRON_BIND_ADDRESS=0.0.0.0:9090

OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...

SPECTRON_SURREALDB_USER=root
SPECTRON_SURREALDB_PASS=changeme

Never commit this file to version control.

systemd service unit

Create the service unit file at /etc/systemd/system/spectron.service:

[Unit]
Description=Spectron – Agentic Memory Layer
Documentation=https://docs.surrealdb.com/spectron
After=network.target
Wants=network.target

[Service]
Type=exec
User=spectron
Group=spectron
EnvironmentFile=/etc/docs/spectron/env
ExecStart=/usr/local/bin/spectrond api start --connection-string ws://127.0.0.1:8000 --bind-address 0.0.0.0:9090
Restart=on-failure
RestartSec=5
TimeoutStopSec=30

# Harden the service
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ReadWritePaths=/var/lib/spectron

# Logging
StandardOutput=journal
StandardError=journal
SyslogIdentifier=spectron

[Install]
WantedBy=multi-user.target

Enabling and starting the service

Reload systemd to pick up the new unit, then enable and start the service:

systemctl daemon-reload
systemctl enable spectron
systemctl start spectron

Check the service status:

systemctl status spectron

First-run initialisation

On the first run, create the admin management key. Stop the service first to avoid concurrent init operations, or use the spectron init command directly (it is safe to run against a running instance):

sudo -u spectron SPECTRON_SURREALDB_URL=ws://127.0.0.1:8000 \
  spectron init --admin-key

Copy the printed management key secret. Store it in a secrets manager or a separately access-controlled file. It is not recoverable.

Log management

Spectron logs to the systemd journal. Use journalctl to view logs:

# Follow live logs
journalctl -u spectron -f

# Last 200 lines
journalctl -u spectron -n 200

# Logs since yesterday
journalctl -u spectron --since yesterday

Systemd's journal handles log rotation automatically. Configure retention limits in /etc/systemd/journald.conf if needed (SystemMaxUse, MaxRetentionSec).

Health check

Verify the service is responding:

curl http://localhost:9090/api/v1/health

{ "status": "ok", "surrealdb": "connected", "object_store": "ok" }

Upgrading

Pull the new container image, extract spectrond again (same steps as above), replace /usr/local/bin/spectrond, and restart the service. Schema migrations run automatically on startup.

systemctl restart spectrond
journalctl -u spectrond -f

Firewall

Expose port 9090 only to trusted clients. If Spectron sits behind a reverse proxy, bind the application listener to 127.0.0.1 and expose only the proxy's port externally:

# In /etc/docs/spectron/env, restrict to loopback:
SPECTRON_BIND_ADDRESS=127.0.0.1:9090

Next steps

• Architecture overview – component relationships

• Storage and scaling – configuring object store backends

• Authentication – key management after initial setup