Using your node: access and roles.
A single Semurg node ships as a sovereign appliance. It listens on plaintext HTTP at port 4000 and, by default, does not authenticate callers, does not terminate TLS, and does not install a firewall.
Read and write endpoints are reachable by anyone who can reach the port, so you must run the node behind your own network perimeter: bind it to localhost or a private interface, put TLS and access control in front of it, and firewall the port. The one hard guarantee the engine enforces itself is single-writer safety: a POSIX file lock prevents a second process from opening the write log and corrupting your data, so only one writer is ever live.
Write access today is an instance-level licence capability, not a per-user permission: the free single-node build is fully writable by design, and the node does not yet distinguish read-only, read-write, or admin clients at the request boundary. Administration is performed on the host itself through systemd and the node's control shell, which anyone with operating-system access to the machine controls. Per-user and per-scope authorization is on the roadmap and is not enforced in this release.
Run it behind your perimeter.
The node does not protect itself at the network. Your perimeter is the access control that actually exists on the day you download it, so put it in place before you expose the port.
- Bind the node to
127.0.0.1or a private interface, not a public one. - Put TLS and an authenticating reverse proxy in front of it.
- Firewall port 4000 so only trusted hosts can reach it.
- Restrict operating-system access and the node's control credentials to the operator.
What the node actually distinguishes today.
At the request boundary, one node makes exactly the distinctions below. Everything marked no is your perimeter's job, not the node's.
| At the request boundary | Enforced by the node today |
|---|---|
| Read-only vs read-write vs admin user classes | no |
| Authentication, session, or API key | no |
| TLS termination | no |
| Firewall on the port | no |
| Single-writer safety (a second process cannot open the write log and corrupt the store) | yes, POSIX file lock |
| Whether the instance accepts writes at all (a licence capability, instance-wide) | yes, not per-caller |
Administers the host, not an app role.
Administration happens on the machine, not through an application login. You manage the service with
systemd (systemctl start / stop / restart / status semurg) and read its logs with
journalctl. You change configuration by editing /etc/semurg/semurg.env. The
node's control shell, bin/r11 remote, is a full administrative console with total control over
the running node, gated only by operating-system permissions on the node's control credentials.
SEMURG_BENCH_ADMIN_TOKEN gates dataset-load.
The enforced control boundary is operating-system access to the box: the login shell plus the node's control credentials. Anyone with OS access to the machine controls it.
Someone on the same network who is not the operator.
A non-operator on the same network reaches the same :4000 routes as everyone else, with
no session, no token, and no API key.
Nothing distinguishes them from the operator at the request boundary. The request rate-limiter is denial-of-service protection, not authentication.
The read surface, and why read-only is not a per-client class.
The read surface is GET /v1/status, POST /v1/query (fetch, resolve,
search, histogram), and the GET /api/* reads.
Read-only is not a per-client class today. Whether a node accepts writes is an instance-wide property of its licence, not a per-caller permission.
Full access, and why every reachable client has it.
Writes go through POST /v1/ingest, a batch of uniform containers appended to the
store.
The write path checks one instance-level licence capability, and the free build ships that capability on by design, so the endpoint is writable by any caller that can reach the port. The single-writer file lock prevents a second writer process from corrupting the store, but it is a durability guard, not a request authorization.
Designed, not yet enforced.
- Per-request capability tokens that derive read, write, and admin rights, deny by default.
- Localhost binding by default, so a fresh node is not reachable off the box until you open it.
- Per-scope stores, so a capability is scoped to one store.
These are on the roadmap and are not enforced in this release. Until they ship, the distinctions above do not exist at the port, and your perimeter is the boundary.