CLI
Run the Loams engine locally, against your bucket, or as a cluster.
The engine binary is loams. Build it from the source repository; use the binary's help as the authority for your checkout:
cargo run --release -p loams -- --help
cargo run --release -p loams -- dev --help
cargo run --release -p loams -- standalone --help
cargo run --release -p loams -- cluster --help| Command | Purpose |
|---|---|
loams dev | Everything in one process, with data in a local directory |
loams standalone | Everything in one process, with data in an object-storage bucket |
loams cluster | One node of a multi-node cluster |
loams warm <ns>/<collection> | Warm a collection on the node that owns it (--server, default http://127.0.0.1:8080) |
loams durable migrate | Create or update the durable store's schema, then exit |
loams auth new-key | Mint an API key for LOAMS_AUTH_MODE=apikey |
loams pg-control, loams pg-api-key | Loams Postgres's control plane and its API keys; only with the postgres Cargo feature |
Local development
cargo run --release -p loams -- devRuns the engine in one process, with the embedded metastore and local bucket under .loams/ by default. Override --data-dir for isolated development instances and --listen for the native HTTP address. --meta tikv://<pd-host:port>/<keyspace> runs the metastore on TiKV instead (tikv Cargo feature).
Object-storage deployment
cargo run --release -p loams -- standalone --bucket s3://my-bucket/loams --flight-sql-listen 127.0.0.1:8082Runs a single engine process against an object-storage bucket (s3://, gs:// or file:/// URLs). Unlike dev, standalone defaults Flight SQL to 0.0.0.0:8082; with authentication off the engine refuses to start on a non-loopback address, so bind it to loopback as above or enable authentication. Set the selected provider's credentials, retain the metadata directory, and review the operations design. Object storage does not eliminate durable metadata requirements.
Cluster deployment
loams cluster runs one node with --node-id, --roles (a subset of meta,log,query,worker,gateway), --listen, --peers, --bucket, --zone and --replication. Its internal routes are unauthenticated, so --listen must be on a private network, and a cluster node refuses any LOAMS_AUTH_MODE but off. Cluster nodes do not serve Loams Graph or Live. Inspect cluster --help and the architecture before choosing topology.
Default listeners
| Surface | Address | Controls |
|---|---|---|
| Native REST and Connect | 127.0.0.1:8080 | --listen |
| Flight SQL | 127.0.0.1:8082 | --flight-sql-listen, --no-flight-sql |
| Qdrant REST | 127.0.0.1:6333 | --qdrant-listen, --no-qdrant |
| Qdrant gRPC | 127.0.0.1:6334 | --qdrant-grpc-listen, --no-qdrant |
| Elasticsearch REST subset | 127.0.0.1:9200 | --es-listen, --no-es |
| Loams Live sync | 127.0.0.1:7710 (loopback only) | Default live feature; --live-listen, --live-store, --no-live |
| Loams Durable / Resonate | 127.0.0.1:8001 (loopback only) | Optional durable Cargo feature; --durable-listen, --no-durable |
| Postgres wire reads | Off | Optional pgwire feature; --pg-listen, --pg-namespace |
| MySQL wire reads | Off | Optional mysql-wire feature; --mysql-listen, --mysql-namespace |
| Native stream gRPC | Off | Optional stream-grpc feature; --stream-grpc-listen |
Flight SQL defaults to 0.0.0.0:8082 on standalone. Availability depends on the build features. The default engine features are es, flight, hnsw, live and qdrant; tikv, live-tikv, durable, graph, pgwire, mysql-wire, stream-grpc, sqldb and postgres are opt-in. The Loams 0.1.0 loams container image is built with live,live-tikv,durable,graph,tikv,pgwire,mysql-wire,stream-grpc.
Live
Live runs by default on an embedded store under <data-dir>/live/. With the live-tikv feature, --live-store tikv://<pd>[,<pd>]/<keyspace> keeps it on TiKV; --live-pd and --live-keyspace are deprecated aliases. A build without live-tikv refuses those flags.
Enable Durable
cargo run --release -p loams --features durable -- devThis embeds Resonate with SQLite execution state. --durable-store also accepts tikv://<pd-hosts>/<keyspace> (feature durable-tikv, in progress) and the legacy mysql://… (feature durable-mysql); loams cluster needs a shared store. loams durable migrate --durable-store … runs the schema migrations, which standalone and cluster never run on a MySQL store. See the Durable design.
Enable Graph
cargo run --release -p loams --features graph -- devThis serves loams.graph.v1 (GQL on embedded Grafeo) on the native port. dev keeps graphs under <data-dir>/graph; standalone refuses to start without --graph-data-dir, --graph-ephemeral or --no-graph. Without the feature, graph RPCs answer feature_not_in_variant.
Authentication
LOAMS_AUTH_MODE picks how the engine authenticates the native port, Qdrant, Elasticsearch and Flight SQL:
| Mode | Credentials |
|---|---|
off (default) | None; the engine starts only when every listener is on loopback |
apikey | Authorization: Bearer lk_…, checked against hashes in LOAMS_API_KEYS_FILE. Create keys with loams auth new-key --label <name> [--append <file>] |
oidc | JWTs from LOAMS_OIDC_ISSUER for LOAMS_OIDC_AUDIENCE, admitted by LOAMS_OIDC_ALLOWED_EMAILS, _SUBJECTS or _GROUPS |
tailscale | The identity tailscale serve adds, honoured only on LOAMS_TAILSCALE_LISTEN (127.0.0.1:7781) and optionally narrowed by LOAMS_TAILSCALE_ALLOWED_USERS |
Modes combine as a comma list, such as oidc,apikey. /health and /ready stay public.
Use /health for process health and /ready for readiness. Stop with Ctrl+C. Each release publishes Linux packages, macOS tarballs and a Windows zip, and container images. CLI packaging, installers, and agent bootstrap are documented in the CLI design; proposed release commands are not a published installation path.