Install, operate, and query.

Everything below is verified end to end on clean machines. Nothing here is aspirational. A single standalone node is free, self-hosted, with no time limit and no phone-home. You install one command, and it comes up serving on port 4000.

One command on a fresh Ubuntu box.

That is the whole thing. It is idempotent, so re-running it is safe, and it fails with a plain reason rather than a stack trace. You do not need a compiler or any separate language runtime to install. The release bundles everything it needs and the engine ships prebuilt.

Requirements

Recommended, not required: a CPU with AVX-512 for the fastest path (older CPUs use a compatible fallback; check with grep -o avx512f /proc/cpuinfo | head -1), NVMe SSD, two or more disks (it spreads across every disk it finds), 32 GB or more RAM for a larger hot set.

The seven steps you will see

• Preflight. Ubuntu version, glibc, root, internet, minimum CPU/RAM/disk.
• Hardware scan. Physical cores to parallelism, data disks to storage roots, RAM to the in-memory cache budget (about 20%, capped at 32 GiB), CPU features to the matching build.
• Dependencies. Only the runtime shared libraries the bundled runtime needs.
• Engine. Unpacks the release, tunes itself to your core count, selects the build that matches your CPU, and proves the accelerated path engages. If it does not, it falls back to a compatible build; if that fails too it stops rather than run degraded.
• Configure. Writes /etc/semurg/semurg.env and creates the data directories.
• Licence. Installs and verifies the offline Ed25519 licence.
• Start and verify. Waits for engine engaged in the log and HTTP 200 on /api/health, then prints the URL.

Optional overrides

Set before running to override the hardware scan.

Run it in a container (Docker)

The bare-metal installer above is the primary path. If you would rather run in Docker, the image comes up armed or exits with a loud, exact fix, never a silently degraded node. It is x86_64 only. The one-command path builds the image locally (pulling and checksum-verifying the signed release from one.semurg.io) and supplies all three settings the fast disk path needs:

First run builds the image (about two minutes); later runs start in seconds. When it is armed the log prints [semurg-prove] ARMED: cold-op self-test PASSED. The compose file publishes the node on host loopback 4100, so open http://127.0.0.1:4100/api/health.

Prefer explicit flags? Build the image once, then run it yourself. These four are the whole minimal set, nothing else (no --privileged, no --device, no --shm-size, no special mounts):

Both paths publish the node on host loopback 4100 (the container always listens on 4000 inside), so the node is at http://127.0.0.1:4100 either way. Keep the 127.0.0.1: prefix so the port stays private.

The fast path uses large memory pages when available and falls back gracefully, so no special reservation or mount is needed. On Docker Desktop (Mac/Windows) a named volume is ext4 inside the Docker VM and works; a host-folder bind-mount does not. If any capability is missing the container exits non-zero and prints the exact flag and corrected command.

Run it through the service manager.

systemctl status semurg      # is it running
journalctl -u semurg -f      # live logs
systemctl restart semurg     # apply config changes
systemctl stop semurg

Inside a container without systemd, the installer prints the equivalent commands for the background daemon. The installer writes /etc/semurg/semurg.env (data dir, stripe roots, cache budget, port, licence path); edit it and restart to change configuration.

Load a graph bigger than memory (optional)

A fresh node comes up empty: the large public graphs are not bundled in the download, so a just-installed node holds only what you put in it. To watch the out-of-core traversal survive on a graph larger than RAM, load a large public knowledge graph yourself (a Wikidata dump, roughly 100 million entities and over a billion statements, or an OpenStreetMap extract) or a redacted slice of your own data. The reproducible loading kit lives on data.semurg.io and the universal ingestor; there is no one-line sync switch today, so follow the kit. A full Wikidata graph is hundreds of GB raw and more once ingested, so budget the disk. Until you load one, the graph benchmarks (graph_teps, reads, scans) return dataset not staged; the synthetic saops and writes kernels need no dataset and run immediately.

Backups

The store is a single append-only file. Back it up by copying the store directory while the service is stopped. The offline Ed25519 licence never phones home and fails closed, so an air-gapped restore works the same as an online one.

What keeps the data safe, stated plainly.

Disk is the source of truth

The store is a single append-only file on disk. RAM is a pipe for reads, not a second copy. There is nothing separate to replay after a crash, because the file itself is the record.

What a single node survives, and what it does not

Ingest is append-only and lands on disk with no fsync in the path. Writes go straight to disk, so there is no OS write cache in the way. An acknowledged write survives a process crash: kill the writer mid-ingest and, on restart, every acknowledged write is recovered from the same disk. That is tested with kill -9. Durability against a power cut depends on the drive's power-loss protection, which is why enterprise NVMe is the target and why there is no fsync in the hot path. What a single node does not survive is losing the machine or its disk. Surviving that needs a copy on a second machine, and active-active replication is designed and simulated but not yet wired into the running service, so today Semurg runs as a single-writer, single-node store. Run one writer per store; a second process opening the same store is unsafe, so restart only through the service manager.

Authorization: single-writer today, structural by design

The one authorization control the node enforces today is single-writer safety: a file lock keeps a second process from opening the store, so only one writer is ever live and the store cannot be corrupted by a stray second instance. Per-caller and per-scope authorization, a capability checked in the engine rather than bolted on at the API surface, is the design and is on the roadmap; it is not enforced in this release. On a single node today, any client that can reach the port can read and, on the free build, write. See Using your node: access and roles for exactly what each user class can and cannot do.

Network and TLS: your perimeter

The node speaks plain HTTP on the port you choose and does no TLS termination or network-level auth of its own. That is out of scope on purpose. Run it behind your own perimeter (a reverse proxy, a private network, an air-gap), the same place your other internal services already live. Nothing about the node phones home, with or without a network.

One append-only log, and what churn does to it.

How the store is laid out

Semurg is one append-only store per node. Related records are written together, so a node and its edges land side by side. A background process keeps the working set compact. The fast read image is rebuilt clean at a checkpoint; in this build a checkpoint runs at ingest.

Honest consequences

Every performance number we publish is measured on a freshly-ingested store, its densest state. As you edit existing records, those reads resolve from the newest writes rather than the compact image, so an edited store reads progressively more scattered until the next checkpoint rebuilds the image. The append-only file is not yet reclaimed on disk, so superseded bytes from edits persist and the file grows with churn. On-disk compaction is in progress, not shipped.

Load your data, then read it ten ways.

Check the instance first. This reports the licence, whether the instance is writable, and where the customer-data store lives.

{"ok":true,
 "store":{"state":"open","path":"/data0/semurg_store/user_store/user.bin","shards":null},
 "writable":true,
 "api":"semurg /v1 data api",
 "licence":{"id":"FREE-SINGLE-NODE","expiry":"2099-12-31","caps":"core,platform,write"}}

Ingest (batch first)

One request carries a batch of compact containers and costs exactly one crossing into the engine. There is no per-item endpoint by design. Up to 65,536 containers per request; send successive batches for more. Ingest is append-only and lands on disk, with no fsync in the path.

{"ok":true,"containers":65536,"bytes":4194304,"elapsed_us":<elapsed>,"containers_per_s":<measured on your box>}

The public reference box's /v1 store is intentionally empty, so run ingest and query on your own instance. The response above was captured on a 6-core container during verification.

Query

There is also a binary twin, POST /v1/fetch_batch: send a packed array of little-endian u64 ids (application/octet-stream) and get back the matching raw container bytes in request order, in a single crossing into the engine, no JSON/base64 wrap.

Memory your agents share.

This is the capability the product is named for, and it is on by default. Agents — any vendor, any device — that point at the same node and the same scope share one memory. The store is durable, under your data directory, and survives restarts.

Check it is live:

Four verbs, and that is the whole surface:

Remember something. Text is extracted into entities and relationships in the background, so this returns "status":"queued" immediately — give it a few seconds before you recall.

Recall by naming an entity. Recall walks the graph outward from an entity it can match, so ask about a thing — "Acme Corp" — not a free-text question:

The operator control plane.

Your node runs a private operator console: a live cluster graph, the node monitor, mechanism liveness (is the conveyor, janitor and prefetch actually armed right now), extensions, and settings. It binds a loopback-only listener, is fail-closed behind PBKDF2 + a mandatory authenticator code, and is never exposed on the public network.

Your node printed the console URL and a one-time credential on first start, under CLUSTER ADMIN CONSOLE (first-run bootstrap). To read it back out of the boot log:

Opening it from your laptop, and the SSH-tunnel one-liner, are on the cluster admin page.

The same call on both boxes.

Every figure the site publishes is measured live and reproducible by the same call on your own instance. These point only at always-available surfaces: the synthetic saops kernel, and the pre-staged public SNAP graphs. A large loaded graph such as Wikidata is described in prose only, because it returns 503 while warming after a restart.

{"result":{"nodes_visited":1502868,"edge_hops":30120283,"teps":<measured on your box>},
 "dataset":"pokec","benchmark":"graph_teps",
 "provenance":{"note":"whole-graph parallel k-hop BFS across all cores over the compact image; measured live on this box, download the dataset and re-run",
   "dataset_nodes":1632803,"dataset_edges":30622564}}

Returns the SAOPS kernel figure, single-stream and parallel write throughput, and a measured_live_on field that names the box and its physical core count, so you can put your instance's numbers side by side with these. The identical call runs on your localhost:4000 after install; on the public reference box pokec is pre-staged. On your own fresh node the SNAP graphs are not bundled, so load a dataset first (a fresh node returns dataset not staged until you do); the identical call then works.

Worth saying up front.

BM25 relevance ranking over a large text corpus is Elasticsearch's home turf. Sublinear approximate nearest-neighbour at billion-vector scale is what the dedicated vector databases are built for; we do exact search over compact binary codes with recall published honestly, not approximate ANN, which at scale we concede to the specialist indexes. Uniform-random access over payload is bounded by physics for us exactly as it is for everyone else.

We also do not claim to run without indexes. Truth is the store; indexes are bounded and re-derivable from it. The bet is bandwidth: scan and fuse at the drive's sequential ceiling rather than maintain a pile of structures that each need their own copy of your data.

The ten faces are not all equal, so we tag each one. A few are shipped query surfaces today (graph, key-value, search, object, OLAP). Several are expressed as scan patterns over the same store, the shared scan or fold framed as that paradigm (SQL, document, time-series, streaming). One is not yet: vector, where we do exact search over compact binary codes (recall published honestly) and no vector set is loaded on the demo box. The collapse wall marks the same tiers on every card.

Every command on this page, curl-tested against the live box.

Read-only endpoints on the public reference box. Each returns HTTP 200 with the field shown; the write and load endpoints return the documented 403 by policy.

Stamped to release R11 (0.1.0). The full install log lives at /var/log/semurg-install.log.