Run Serverless Objects as a service

A node is sobjects up reading a sobjects.toml. With [ingress] or [admin] configured, the supervisor (TLS ingress and loopback admin API) starts first, then the engine.

#Start and stop a node

sobjects up                  # foreground
sobjects up --detach         # background
sobjects status
sobjects logs                # add --supervisor for the ingress and admin log
sobjects down                # waits for the engine to drain and release its lease

The config path defaults to $SOBJECTS_CONFIG, else ./sobjects.toml. Pass --config PATH to use another file.

#TLS ingress

With an [ingress] table, up starts a TLS-terminating reverse proxy in front of the engine. It:

• routes by exact, *.wildcard or * hostname and answers 421 for anything else;
• tunnels WebSocket upgrades;
• replaces client-supplied X-Forwarded-* and CF-Connecting-IP headers with the real peer address;
• optionally redirects HTTP to HTTPS with 308;
• serves /.well-known/sobjects/health, which checks the upstreams at most once a second;
• writes JSON access logs without query strings.

Remote clients of the health endpoint get only {"status":"ok"} or "degraded" (with 503). Loopback clients also see each upstream's address and state.

Plaintext ingress is allowed only on loopback. When [celld].listen is loopback, up starts celld with --trust-forwarded-headers, so a Worker's request.url has the client's https:// scheme and host, as on Cloudflare.

#Static certificates

[ingress]
listen = "0.0.0.0:443"
redirect_http = "0.0.0.0:80"

[ingress.tls]
cert = "/etc/serverless-objects/tls/fullchain.pem"
key = "/etc/serverless-objects/tls/privkey.pem"

[[ingress.routes]]
hostname = "agents.example.com"

Relative paths resolve from the config file's directory. SIGHUP reloads static certificates. A route can carry its own certificate, chosen by SNI: tls = { cert = "...", key = "..." }. Wildcard hostnames need static certificates.

#ACME HTTP-01

[ingress]
listen = "0.0.0.0:443"
redirect_http = "0.0.0.0:80"

[ingress.acme]
email = "ops@example.com"
agree_to_terms = true
directory_url = "https://acme-staging-v02.api.letsencrypt.org/directory"

[[ingress.routes]]
hostname = "agents.example.com"

ACME needs:

The default directory is Let's Encrypt production, so test with the staging directory_url first. Keys and certificates are stored under the state directory with mode 0600 files in 0700 directories. Valid certificates are reused at startup and renewed 30 days before expiry. A failed renewal is retried every six hours while the current certificate is still valid. Issuance has been tested against Pebble; public Let's Encrypt issuance and renewal have not been exercised yet.

#Dashboard and admin API

An [admin] table makes the supervisor serve a dashboard at / and a JSON API:

[admin]
listen = "127.0.0.1:8790"

The dashboard shows node health and load, the objects in each namespace, per-object storage with a key-value browser and read-only SQL console, and eviction. The API listens on loopback only and refuses non-loopback Host headers. Mutations require the x-sobjects-request: 1 header. [admin] is available with [celld] only.

#Admin token

Every local process can reach loopback, including the apps you deploy, so the API also requires an admin token. The supervisor creates it on first start as admin-token in the state directory (a 256-bit random value, mode 0600 in a 0700 directory). Only the dashboard's static files, GET /api/v1/health and GET /metrics work without it.

Run sobjects dashboard as the same user and with the same SOBJECTS_STATE_DIR as sobjects up:

sobjects dashboard
# http://127.0.0.1:8790/#token=...

The token travels in the URL fragment, which browsers don't send to the server. Treat the URL like a password. To rotate the token, stop the supervisor, delete admin-token and start it again.

From a script, send the token as a bearer token:

curl -H "Authorization: Bearer $(cat "${SOBJECTS_STATE_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/serverless-objects}/admin-token")" \
  http://127.0.0.1:8790/api/v1/node

#Endpoints

celld 0.6 has no storage API, so sobjects deploy wraps the app's Durable Object classes in a small inspection hook. Requests carrying x-sobjects-inspect with this host's token are answered by the hook, and everything else reaches the app unchanged. Only the token's SHA-256 goes into the bundle, and the ingress strips the header from client requests. Pass --no-inspector to deploy without it.

#Service units

sobjects service print writes a systemd unit (Linux) or launchd plist (macOS) to stdout. --kind overrides the choice. sobjects service install writes it to disk, refuses to overwrite without --force, and prints the enable commands. It doesn't start anything.

sobjects service print --config /etc/serverless-objects/sobjects.toml
sobjects service install --config /etc/serverless-objects/sobjects.toml --system --user sobjects

The unit runs sobjects up in the foreground and restarts it on failure. systemd units read credentials from an optional sobjects.env beside the config. System units get CAP_NET_BIND_SERVICE so the ingress can bind ports 80 and 443. Review the generated unit before you enable it.

#Native engine nodes

A [native] table in place of [celld] makes up run the native engine. --detach, status, logs, down and service install work the same way, and [ingress] routes to [native].listen by default. [admin] and the dashboard aren't available with [native] yet, and sobjects deploy is for celld: restart the node to run new code. See native engine and benchmarks.

#Security checklist

• Keep celld's listener, its operator listener and the admin API on loopback. Only the ingress should face the network, and it requires TLS to do so.
• The admin token guards the admin API against other local processes. It is not a reason to expose the API.
• Keep object-store credentials in the environment, the credential chain or sobjects.env, never in sobjects.toml.
• Use a bucket dedicated to Serverless Objects.