Deploying a server

When to use a server

LoonFS can be used as an embedded runtime talking directly to the object storage backing store, or hosted on a server to support remote clients.

The most helpful heuristic to anticipate the need for a server host:

• More than one client will be writing to the same namespace concurrently (a server safely serializes multiple writers into a single commit stream).
• The client cannot be trusted to talk directly to the object store (e.g., in a multi-tenant application).

See profiles and deployment modes to learn more.

Server topology

Run one active LoonFS server per deployment. One server can support a large number of active namespaces.

The reference server does not support automatic failover or horizontal scaling. A restart or upgrade will make the API briefly unavailable, but all durable state is stored in object storage (the memory and SSD caches are always rebuildable, and never authoritative).

Deploying the server

The complete self-hosting guide covers server config, Docker and Helm deployment, TLS, authentication, secrets, health checks, metrics, resource sizing, upgrades, and more.

The high level summary:

1. Choose an object store and create a server config.
2. Set LOONFS_AUTH_TOKEN and LOONFS_CONTENT_TOKEN_SECRET in the secrets manager.
3. Terminate TLS in LoonFS (or a trusted proxy).
4. Validate deployment with loonfs-server --config ... --check-config.
5. Verify /health, /readiness, loonfs maintenance store probe, and a write/read round trip.

Connecting clients

Once deployed, clients can connect to a LoonFS server using a remote profile:

export LOONFS_AUTH_TOKEN={auth_token}

loonfs --no-input profile create remote production \
  --server-url {server_url}

loonfs profile use production

Application clients

Applications can use the HTTP API directly or the native TypeScript, Python, and Go SDKs. The embedded Rust runtime and remote Rust client share the same operation types and capability model.