§30 Loams CLI, Installer and Agent Bootstrap

Status: Proposed · 2026-10-01. The direction is the owner's. On 2026-10-01 the owner asked to fold the first draft in chatdump.md (an earlier chat) into the design docs, the decision log and the plans. The direction from that draft is: a one-line installer (curl -fsSL https://loams.dev/install.sh | sh); one loams binary that is both the CLI and an MCP server (loams mcp serve); AWS-style commands (configure, stack create|describe|list|delete, keys, env export, mcp install --agent …, pkg add, self-update); prebuilt feature-set variants instead of building on the user's laptop; NVMe set up for the foyer cache; secrets kept out of agent transcripts by writing them to .env.loams; and cargo-dist for releases. This document turns that direction into decisions D281–D299 and open questions Q281–Q294. Every choice that goes beyond the direction (names, formats, safety rules, phasing) is a proposal until the owner confirms it. No code is written by this document.

Markers: (verified 2026-10-01) means checked against a primary source on that date (§23 lists the sources). (verify) means the plan that builds it checks it first. (estimate) means computed, not measured. Paths of the form crates/… point at main at 9eaddae (2026-10-01).

Naming. This document writes loams for the binary and its commands, following the owner's rulings of 2026-10-01 and 2026-10-02 (D400, D401, D406): the binary is loams (answering Q284), packages are loams on crates.io, PyPI and npm (scope @loams; loamdb from D33 is superseded), Go modules are loams.dev/..., the domain is loams.dev and the repository becomes ostrium-labs/loams. The crates (loams, loams-server, loams-cli) follow the same namespace. The local state directory is LOAMS_HOME (default ~/.loams), the variables are LOAMS_* and the env file is .env.loams (D407). Nothing is published before the repository moves to ostrium-labs/loams (D33, D406).

1. SummaryCopy Anchor Link

2. Goals and non-goalsCopy Anchor Link

2.1 GoalsCopy Anchor Link

1. Paste one command and get a working stack. After curl … | sh and loams init, a laptop runs Loams with the Qdrant, Elasticsearch, Flight SQL and MCP surfaces, has a .env.loams its app can read, and has its coding agent connected. No compiler is needed.
2. Agents can drive it. Every command has a stable JSON output and a stable exit code, so a model that already knows aws <service> <verb> can chain commands. The bootstrap MCP tools let an agent read the docs, provision a local stack and install the SDK itself.
3. Credentials stay out of transcripts. No tool output, error, log line or JSON document that an agent can read contains a secret.
4. One artifact per platform and variant, with checksums, provenance and a signature, and a self-update that verifies all three.
5. Buy, not build (user memory). Use clap, cargo-dist, rmcp, Tantivy, minisign-verify, self-replace, toml_edit and the agents' own CLIs. Loams writes only the glue: the engine registry, the stack supervisor, the safety rules and the installer script.

2.2 Non-goalsCopy Anchor Link

• No build step on stack create. Compiling the server takes tens of minutes and several GB of RAM (the M0–M1 build notes). --from-source exists but is never the default.
• No privileged helper or setuid binary. Root is needed only for storage prepare, and the user runs that explicitly under sudo.
• No proxying of the data plane's MCP tools through the stdio server (§12.1).
• No telemetry, crash reporting or usage pings.
• No Windows server. The engine's io_uring paths (§28 §7.2) and its test matrix are Linux and macOS. Windows gets the cli variant after D297 (Q285), and WSL2 otherwise.
• No cloud provisioning in CLI1 or CLI2. Cloud stacks go through Loams Cloud's public API in CLI3 (Q291). The CLI is open source (D220) and never depends on loam-platform code.

3. How this fits what existsCopy Anchor Link

4. The binary and its crates (D281, D297)Copy Anchor Link

4.1 CLI1 layoutCopy Anchor Link

crates/loams-cli/                 # new library crate, no server dependencies
  src/lib.rs                       # pub enum ClientCommand (clap Subcommand), pub async fn run(ClientCommand, &Globals) -> ExitCode
  src/output.rs                    # the D283 contract: Output, Render, CliError, ErrorCode, exit codes
  src/home.rs                      # LOAMS_HOME layout, locks, atomic writes
  src/config.rs  src/configure.rs  # profiles (D284)
  src/engines.rs                   # the engine registry (D285, §8.2)
  src/stack/{mod,spec,resolve,ports,supervise,health}.rs
  src/storage/{mod,lsblk,prepare}.rs
  src/env.rs  src/secret.rs        # .env.loams and Secret (D288)
  src/docs/{mod,bundle,index,snippets}.rs   # the embedded bundle (D291)
  src/mcp/{mod,tools,install,agents}.rs     # stdio server and install (D289, D290)
  src/init.rs  src/version.rs
  build.rs                         # packs docs/guides and docs/snippets into a zstd tarball
crates/loams/src/main.rs          # gains #[command(flatten)] Client(loams_cli::ClientCommand) and the global flags

loams-cli depends on clap, serde, serde_json, toml_edit, reqwest (rustls), tokio, rmcp (features server, transport-io), schemars, tantivy (already in the tree through loams-text), zstd, tar, comfy-table, dialoguer, fs4, nix (Unix process groups and signals) and thiserror. It does not depend on loams, loams-query or any storage crate. The stack commands start the server as a child process and talk to it over HTTP, the same way any client does.

Why one crate with modules and not one crate per group (the chat dump suggested the latter): there would be thirteen small crates, all sharing the output contract, LOAMS_HOME and the engine registry. That means thirteen Cargo.toml files to keep in step and more link units on a build machine where links are the bottleneck. The groups have no independent consumers. Modules give the same separation.

4.2 The server split (D297, CLI2)Copy Anchor Link

The cli variant needs a binary that does not link the engine. Today crates/loams is both the server library and the binary, and its server dependencies are not optional. CLI2 Task 1 moves crates/loams/src/{server.rs, cluster.rs, meta_backend.rs, api/, pg/, mysql_wire/} into a new library crate, loams-server. crates/loams becomes:

• [features] default = ["server", …], with server = ["dep:loams-server"] and every engine feature forwarded (es = ["server", "loams-server/es"], …);
• lib.rs: #[cfg(feature = "server")] pub use loams_server::*;, so crates/loams/tests/** (which use loams::{Server, ServerConfig} and CARGO_BIN_EXE_loams) do not change;
• main.rs: the server subcommands behind #[cfg(feature = "server")]. Without the feature, loams dev exits 6 with this is the cli variant; install the standard variant: loams self-update --variant standard.

The split is mechanical but touches every in-flight crates/loams branch (pg, mysql_wire, durable). It therefore lands right after D33's rename PR, which already invalidates every branch, and not in CLI1.

5. The command tree (D282)Copy Anchor Link

loams [--output table|json|text] [--profile NAME] [--no-input] [--quiet] [-v…] [--color auto|always|never]
├── init                         [--yes] [--stack NAME] [--engines LIST] [--agent AGENT…] [--no-agent] [--no-env]
├── configure                    (interactive: endpoint, default stack, output)
│   ├── get KEY | set KEY VALUE | unset KEY | list
├── stack
│   ├── create   --name NAME [--engines LIST] [--storage dir:PATH|mount:PATH|nvme:DEVICE]
│   │            [--metastore embedded|raft|tikv://PD/KS] [--object-store local|s3://…|gs://…|az://…|file:///…]
│   │            [--variant standard|full] [--port-base PORT] [--file stack.toml] [--no-start]
│   │            [--allow-download] [--from-source] [--wait-timeout 60s]
│   ├── describe [--name NAME]
│   ├── list
│   ├── start    [--name NAME] [--wait-timeout 60s]
│   ├── stop     [--name NAME] [--grace 30s]
│   ├── restart  [--name NAME] [--upgrade]
│   ├── run      --name NAME                           (foreground; for systemd, launchd and containers)
│   ├── logs     [--name NAME] [--follow] [--lines N]
│   └── delete   --name NAME [--keep-data] --yes
├── storage
│   ├── inspect  [DEVICE]
│   └── prepare  --device DEVICE [--mount /mnt/loams-cache] [--fs ext4] [--wipe] --yes     (run with sudo; Linux only)
├── env
│   └── export   [--stack NAME] [--format dotenv|json|shell] [--write PATH] [--merge PATH] [--no-gitignore]
├── keys                                                (CLI3; exits 6 before the auth plan)
│   ├── create   [--stack NAME] [--env ENV] [--name LABEL] [--expires 90d] [--write-env PATH]
│   ├── list     [--stack NAME]
│   ├── rotate   KEY_ID [--write-env PATH]
│   └── revoke   KEY_ID --yes
├── login [--endpoint URL] | logout                      (CLI3)
├── mcp
│   ├── serve    [--stack NAME] [--project-dir PATH]
│   ├── install  --agent claude-code|codex|cursor|windsurf [--scope user|project|local] [--stack NAME] [--no-data] [--dry-run]
│   ├── uninstall --agent AGENT [--scope …]
│   └── tools                                           (lists the bootstrap tools and their schemas)
├── pkg
│   └── add      PACKAGE… [--language typescript|python|rust] [--dev] [--dry-run]       (CLI2)
├── docs
│   ├── search   QUERY [--limit 5]
│   └── snippet  --engine ENGINE --language LANG [--task TASK]
├── self-update  [--check] [--version X.Y.Z] [--variant V] [--rollback] [--yes]        (CLI2)
├── version
├── completions  bash|zsh|fish|powershell|elvish
│
├── dev | standalone | cluster | warm | durable migrate  (the server commands, unchanged)

Rules shared by every group:

6. Output, errors and exit codes (D283)Copy Anchor Link

6.1 FormatsCopy Anchor Link

• table (the default). Human tables (comfy-table) and key/value blocks. Colour only when stdout is a TTY and NO_COLOR is unset. Progress and notices go to stderr.
• json. Exactly one JSON document on stdout, followed by a newline. Keys are snake_case. A list command returns an object ({"stacks": [...]}), never a bare array, so fields can be added. Times are RFC 3339 UTC, sizes are integer bytes, durations are integer milliseconds with an _ms suffix. Nothing else is written to stdout. Notices, progress and update checks are suppressed, and logs go to stderr only with -v.
• text. Tab-separated rows without headers, one record per line, for cut and awk (as the AWS CLI's text output).
• Default selection. --output, then LOAMS_OUTPUT, then the profile's output, then table. The format is never inferred from whether stdout is a TTY: a script must get what it asked for.
• Commands that emit a file format (env export, completions) emit that format unless --output json is given explicitly. With --output json, env export returns {"stack", "path", "variables": {...}}. With --output json, completions returns {"shell", "script"}, where script is the generated completion text as one JSON string.
• mcp serve always writes JSON-RPC to stdout (§12.1). --output does not change its transport. A startup error before the transport opens follows §6.2.

Every JSON output type derives schemars::JsonSchema. The schemas are snapshotted in crates/loams-cli/tests/schemas/*.json and a test fails on any change that is not additive. loams version --output json reports "output_schema": 1, which is bumped only by a breaking change, announced one minor release ahead.

6.2 ErrorsCopy Anchor Link

In json mode an error is one object on stderr, stdout is empty, and the exit code is set:

{"error": {"code": "stack_not_found", "message": "no stack named `dev`", "hint": "run `loams stack list`", "exit_code": 4, "details": {"name": "dev"}}}

In table and text modes the same error prints as error: <message> and hint: <hint> on stderr.

6.3 Exit codesCopy Anchor Link

6.4 Prompts and confirmationCopy Anchor Link

• A prompt appears only if stdin and stderr are both TTYs and none of --no-input, LOAMS_NO_INPUT=1 or CI=true is set.
• Destructive commands (stack delete, storage prepare, keys revoke) need --yes. Interactively they ask instead: y/N for delete and revoke, and for storage prepare the user must type the device path. Without a TTY and without --yes, they exit 3 with confirmation_required.
• A command that needs a download it was not told to make (a variant, §9.3) asks interactively. Otherwise it exits 3 with download_consent_required and the hint --allow-download.

7. Local state (D284)Copy Anchor Link

$LOAMS_HOME (default ~/.loams; mode 0700)
├── bin/loams                       # the installed binary (install.sh, self-update)
├── bin/loams.prev                   # the previous binary, kept by self-update for --rollback
├── env  env.fish                   # PATH snippets, sourced from shell rc files
├── receipt.json                    # {version, variant, target, installed_at, install_method: "install.sh", source_url}
├── config.toml                     # profiles (no secrets)
├── credentials.toml                # 0600; CLI3: login tokens per profile
├── variants/<version>/<variant>/loams  # downloaded server variants (D286)
├── cache/update-check.json         # {checked_at, latest}
├── mcp-installs.json               # what `mcp install` wrote, and where (D290)
└── stacks/<name>/
    ├── stack.toml                  # the resolved spec (§8.1)
    ├── lock                        # fs4 advisory lock: one start, stop or delete at a time
    ├── server.pid
    ├── data/                       # --data-dir (metastore, local bucket) unless --object-store points elsewhere
    ├── cache/  hot/                # H1 and H2 unless --storage points elsewhere
    ├── secrets/                    # 0700; CLI3: the stack's bootstrap key (local stacks only)
    └── logs/server.log             # rotated at 64 MiB, 3 files kept

# config.toml
[profile.default]
endpoint = "local"        # "local" (stacks under LOAMS_HOME) or https://… (CLI3: a remote or cloud endpoint)
default_stack = "dev"
output = "table"
update_check = true

• Writes are atomic: write a temp file in the same directory, fsync, then rename. Secret files are created with mode 0600 before anything is written to them.
• The update check happens at most once a day, in the background of an ordinary command. It reads the release manifest (§17.1) and prints a newer loams (0.5.0) is available: loams self-update on stderr in table mode only. It never runs in json mode, under mcp serve, with CI=true, or with LOAMS_NO_UPDATE_CHECK=1 or update_check = false. It sends no identifiers beyond what an HTTP GET of a public file carries.

8. Stacks (D285)Copy Anchor Link

8.1 The stack specCopy Anchor Link

# ~/.loams/stacks/dev/stack.toml (written by `stack create`; also accepted by `stack create --file`)
name = "dev"
version = "0.4.0"                 # the binary version that created it
variant = "standard"
binary = "/home/u/.loams/bin/loams" # or ~/.loams/variants/0.4.0/full/loams
engines = ["native", "flight-sql", "mcp", "qdrant", "es"]
metastore = "embedded"            # embedded | tikv://<pd-hosts>/<keyspace>
object_store = "local"            # local | s3://… | gs://… | az://… | file:///…
env_passthrough = []              # e.g. ["AWS_PROFILE", "AWS_REGION"] for an s3:// object store

[storage]
kind = "dir"                      # dir | mount | nvme
path = "/home/u/.loams/stacks/dev" # dir: the parent of cache/ and hot/; mount, nvme: the mount point
device = ""                       # nvme only: /dev/nvme1n1 (recorded; never re-formatted)
cache_ram_bytes = 1073741824
cache_disk_bytes = 0              # 0 = RAM only (the default for dir:; §10.3)
hot_nvme_bytes = 0                # 0 = the server default
hot_ram_bytes = 0

[ports]                           # resolved at create time, then fixed
native = 8080
flight_sql = 8082
mcp = 8083
qdrant = 6333
qdrant_grpc = 6334
es = 9200

The server never reads stack.toml. stack run translates it into the server's command line, for example:

loams dev --data-dir ~/.loams/stacks/dev/data --listen 127.0.0.1:8080 \
  --flight-sql-listen 127.0.0.1:8082 --mcp-listen 127.0.0.1:8083 \
  --qdrant-listen 127.0.0.1:6333 --qdrant-grpc-listen 127.0.0.1:6334 --es-listen 127.0.0.1:9200 \
  --no-durable --cache-dir ~/.loams/stacks/dev/cache --cache-ram-bytes 1073741824 \
  --hot-dir ~/.loams/stacks/dev/hot

object_store = "local" runs dev. Anything else runs standalone --bucket <url>. Every address the CLI generates is loopback (D111). Exposing a local stack is outside the CLI: the operator runs loams standalone or cluster directly.

8.2 The engine registryCopy Anchor Link

• --engines defaults to native,flight-sql,mcp,qdrant,es. native is implied: it is the control surface the CLI health-checks.
• Engines that are not asked for are switched off. Engines that are on by default in the server (flight-sql, qdrant, es, durable, mcp) get their --no-* flag. Opt-in listeners get no flag. A variant can therefore serve any subset of its engines.
• pg versus postgres. pg is D-PG-1's Postgres wire over collections: analytics and ingest, read-only by default (PG1). It must not be mistaken for an OLTP database. Its variable is LOAMS_PG_URL, never DATABASE_URL, because ORMs and frameworks treat DATABASE_URL as their OLTP store. postgres is real Postgres (D299). This resolves the chat dump's --engines postgres,qdrant,es: CLI1 rejects postgres with exit 6 (engine_unsupported, hint: "pg is Postgres-wire analytics over collections; OLTP Postgres arrives with companions in CLI3").
• Ports. For the first stack, each engine takes its default port if it is free. Otherwise, and for every later stack, the CLI picks the first free block of 100 ports from 20000 (--port-base overrides). Each port in the block is base plus a fixed offset: native +80, flight-sql +82, mcp +83, stream-grpc +85, qdrant +33/+34, es +92, pg +32, mysql +06, durable +01, live +10, jobs +20. "Free" means a test bind on 127.0.0.1 succeeds at create time, and the ports are written into stack.toml. stack start re-checks them and exits 5 with port_in_use, naming the port, if another process holds one.
• The metastore. embedded (the alias raft is accepted) is the single-node openraft store in data/. tikv://<pd-hosts>/<keyspace> needs the full variant (tikv feature) and maps to --meta. Postgres and DynamoDB come when M2 ships them (D58). There is no TiDB (D260).

8.3 Lifecycle and the supervisorCopy Anchor Link

• stack create resolves the spec (variant, ports, storage) and writes stack.toml. Unless --no-start is given, it then runs stack start, writes .env.loams in the current project directory if there is one (§11.2), and prints the endpoints. It refuses an existing name (exit 5).
• stack start takes the stack's lock and spawns loams stack run --name <n> detached: a new session (setsid), stdin from /dev/null, stdout and stderr appended to logs/server.log. It writes server.pid, then polls GET http://<native>/ready every 200 ms until it returns 200 or --wait-timeout passes. On timeout it exits 7 with the last 20 log lines in details.log_tail.
• stack run is the foreground form. It execs the server binary with the generated flags, so systemd units, launchd plists and containers use the same command line. A --service systemd|launchd generator is a CLI2 follow-up (Q288).
• stack stop sends SIGTERM to the process group, waits --grace (default 30 s, about the server's own HTTP_GRACE plus listener drains), then sends SIGKILL. It removes server.pid.
• stack describe reports one of running (the pid is alive and /ready returns 200), starting, unhealthy (alive but not ready), stopped or crashed (a pid file whose process is gone). It also reports the endpoints, the variable names, the binary and its version, and binary_outdated if the stack's binary is older than the installed one.
• stack delete --yes stops the stack and removes stacks/<name>/. It never deletes a remote bucket's objects or unmounts a disk; it prints what it left in place. --keep-data keeps data/.
• stack restart --upgrade switches binary to the installed binary (or the matching variant) and restarts. Data stays, under the format N/N−1 rules of §10 §7.

{"name": "dev", "state": "running", "pid": 41233, "version": "0.4.0", "variant": "standard",
 "binary": "/home/u/.loams/bin/loams", "binary_outdated": false, "metastore": "embedded", "object_store": "local",
 "storage": {"kind": "nvme", "device": "/dev/nvme1n1", "path": "/mnt/loams-cache", "cache_disk_bytes": 858993459200},
 "engines": [
   {"engine": "qdrant", "endpoints": {"rest": "http://127.0.0.1:6333", "grpc": "http://127.0.0.1:6334"}, "env": ["QDRANT_URL", "QDRANT_GRPC_URL"]},
   {"engine": "es", "endpoints": {"rest": "http://127.0.0.1:9200"}, "env": ["ELASTICSEARCH_URL"]}],
 "auth": "none", "created_at": "2026-10-01T09:12:44Z"}

9. Variants and the feature matrix (D286)Copy Anchor Link

9.1 Why prebuiltCopy Anchor Link

Building loams with release settings takes tens of minutes and several GB of RAM on a laptop (estimate, from the M0–M1 build notes; this machine hangs on fully parallel builds). Toggling durable alone rebuilds about 480 crates (D262). "Paste one command" cannot include that. The chat dump also chose prebuilt variants for this reason. A variant can switch off engines at run time (§8.2), so two server variants cover every combination; neither is a per-stack build.

9.2 The matrixCopy Anchor Link

• Durable in standard. D262 says release builds turn durable on, so the standard variant includes it. Stacks that do not ask for it pass --no-durable.
• pgwire in standard. PG1 Task 1 decides whether pgwire becomes a default feature. The variant includes it either way, because the listener is off unless --pg-listen is given.
• Targets. x86_64-unknown-linux-gnu and aarch64-unknown-linux-gnu are built on Ubuntu 22.04 runners, so the minimum glibc is 2.35 (verify that cargo-dist's min-glibc-version check agrees). aarch64-apple-darwin is built on a macOS 15 runner. Intel macOS servers are not built (Q286). musl is not built: the engine's allocator and DataFusion's performance on musl are untested.
• A CI guard (CLI2 Task 3) parses release/variants.toml and fails if a variant enables failpoints, cluster-tests or durable-mysql, or if a variant's feature list differs from cargo metadata's view of the loams features.

9.3 Selecting a variant at stack createCopy Anchor Link

1. Compute the features the requested engines need (§8.2).
2. If the running binary's compiled-in features (env!-baked by build.rs into loams_cli::version::FEATURES) cover them, the stack uses the running binary.
3. Otherwise, take the smallest variant in the release manifest that covers them, at the same version as the running binary. If it is already in variants/<version>/<variant>/, use it. If not, download it with the self-update verification path (§17.3), with consent (--allow-download, or a prompt).
4. If no variant covers them, exit 6 (feature_not_in_variant) and name the missing features. --from-source then runs cargo install --locked --git https://github.com/ostrium-labs/loams --tag v<version> loams --no-default-features --features <list> --root ~/.loams/variants/<version>/src-<hash>/, after warning about time and memory. It needs a Rust toolchain and is never chosen automatically.

10. NVMe and the cache (D287)Copy Anchor Link

10.1 What gets placed on the deviceCopy Anchor Link

§04 puts H1 (byte ranges of durable objects: Lance pages, split blocks, segments) in foyer's hybrid RAM and NVMe cache, and H2 (HNSW artifacts and pinned splits) on local disk. In code, H1 is loams_cache::RangeCache with RangeCacheConfig { block_size, memory_bytes, disk: Option<DiskConfig { dir, capacity_bytes }> }, and H2 uses --hot-dir and --hot-nvme-bytes. H1's disk tier has no flag today, so CLI1 Task 3 adds three flags to the shared Native group on dev, standalone and cluster:

These are the M1-era flag forms of §10 §2's [cache] nvme_path and nvme keys, and §10 §2's flag table gains these rows.

10.2 The flowCopy Anchor Link

loams stack create --name dev --storage nvme:/dev/nvme1n1
  ├─ device mounted already? ──yes──► use <mountpoint>/loams/<stack>/{cache,hot}; check that the user can write there
  └─ no ──► running as root? ──no──► exit 3 (sudo_step_required) and print:
                │                       sudo loams storage prepare --device /dev/nvme1n1 --mount /mnt/loams-cache --yes
                │                       loams stack create --name dev --storage mount:/mnt/loams-cache
                └─ yes ──► refuse: exit 3 ("run `storage prepare` under sudo, then `stack create` as yourself")

stack create never formats anything. Only storage prepare writes to a device, and only when the user ran it explicitly as root.

loams storage prepare --device D --yes (Linux only; elsewhere exit 6, platform_unsupported) does the following:

1. Inspects the device with lsblk --json --bytes --output NAME,PATH,TYPE,SIZE,FSTYPE,MOUNTPOINTS,PKNAME,MODEL,SERIAL,ROTA,RO and blkid -p -o export D (util-linux).
2. Refuses (exit 5, nothing written) if any of these holds:
   • D is not a block device of TYPE disk or part (loop and dm devices need --allow-virtual, which CI uses);
   • D or any of its partitions is mounted, holds swap or /, or is an LVM, MD-RAID or ZFS member;
   • D is read-only;
   • D is smaller than 16 GiB;
   • D has a filesystem or partition-table signature and --wipe was not given (device_has_filesystem names the signature);
   • D is rotational and --allow-hdd was not given.
3. Confirms. With a TTY, the user must type D's path. Without one, --yes is required.
4. Formats with mkfs.ext4 -F -L loams-cache -m 0 -E lazy_itable_init=1,discard D. ext4 is everywhere and needs no extra tools. XFS is an option (--fs xfs).
5. Mounts with mount -o noatime D <mount>, then appends UUID=<uuid> <mount> ext4 noatime,nofail 0 2 to /etc/fstab. A line for that UUID is never written twice. --no-fstab skips this step.
6. Hands the mount over: chown $SUDO_UID:$SUDO_GID <mount>, then mkdir <mount>/loams.
7. Prints --storage mount:<mount> for the next command. With --output json it returns {device, uuid, mount, fs, size_bytes, fstab: bool}.

The step list is a pure function, plan_prepare(&Lsblk, &Blkid, &Options) -> Result<Vec<Step>, Refusal>, tested against fixture JSON. Execution runs std::process::Command per step with no shell. A CI job (cli-nvme) runs the whole flow as root against a loop device backed by a sparse file (CLI1 Task 7).

10.3 SizingCopy Anchor Link

The remaining 10 % is headroom for ext4 and for foyer's own overheads. Both values can be overridden with stack create --cache-disk-bytes and --hot-nvme-bytes.

11. Secrets (D288)Copy Anchor Link

11.1 The ruleCopy Anchor Link

A secret never appears in MCP tool output, MCP errors, json output that an agent might read, log lines or panic messages. Secrets are written to files with mode 0600, and only names and redacted values are reported.

• loams_cli::secret::Secret(String) implements neither Serialize nor Display. Its Debug prints Secret(<redacted>). The only way to read it is expose(&self) -> &str, called in two places: the dotenv writer, and the HTTP client's auth header. A clippy.toml disallowed-methods entry stops expose from being called anywhere else in the crate without an #[allow] that names this section.
• The canary test (CLI1 Task 9) creates a stack whose secrets/ holds the canary loams_cnry_9f2b…, calls every MCP tool with valid and invalid arguments, runs every CLI command in json mode, scans the stdout, stderr and server.log it captured, and fails if the canary appears anywhere.
• Humans still see their secrets when they ask: keys create in a terminal prints the token once. env export prints it when the user runs it directly. Only the MCP path is restricted.

11.2 .env.loamsCopy Anchor Link

# Written by loams 0.4.0 for stack "dev" at 2026-10-01T09:12:44Z. Do not commit.
LOAMS_STACK=dev
LOAMS_URL=http://127.0.0.1:8080
LOAMS_FLIGHT_SQL_URL=grpc://127.0.0.1:8082
LOAMS_MCP_URL=http://127.0.0.1:8083/mcp
QDRANT_URL=http://127.0.0.1:6333
QDRANT_GRPC_URL=http://127.0.0.1:6334
ELASTICSEARCH_URL=http://127.0.0.1:9200
# No API key: this stack serves loopback without auth (D111). `loams keys create` arrives with the auth plan.

• Loams owns .env.loams entirely. Each write replaces it atomically, with mode 0600. Writing to it is idempotent.
• --merge PATH (for example --merge .env) updates the variables between # >>> loams (stack dev) >>> and # <<< loams <<< markers in place, inserting the block if it is absent. Lines outside the block are never changed. This replaces the chat dump's loams env export >> .env, which duplicates lines on every run. The plain >> form still works, and the docs recommend --merge.
• .gitignore. If the project is a git repository and git check-ignore -q .env.loams fails, the CLI appends .env.loams to .gitignore and says so on stderr. --no-gitignore skips this.
• Variable names. The chat dump's LOAMS_KEY_ID stays (it is not secret, and logs may print it). LOAMS_KEY_SECRET becomes LOAMS_API_KEY, the whole loams_<key_id>_<secret> token (D65), because the SDKs and gateways need the whole token. QDRANT_API_KEY and ELASTICSEARCH_API_KEY carry the same token, since the Qdrant api-key header and the ES ApiKey scheme accept it (§10 §4). DATABASE_URL is set only by the postgres companion (§8.2).
• The project directory is --project-dir, else $CLAUDE_PROJECT_DIR (which Claude Code sets for MCP servers, verified 2026-10-01), else the nearest ancestor of the working directory that holds .git, package.json, pyproject.toml or Cargo.toml, else the working directory.
• Agents with file access can still read .env.loams. The rule keeps the secret out of tool output, not out of an agent that runs cat. For Claude Code with project scope, mcp install therefore offers to add "permissions": {"deny": ["Read(./.env.loams)"]} to .claude/settings.json (only with consent, interactively or with --protect-env). The guide recommends the equivalent for other agents.

12. MCPCopy Anchor Link

12.1 loams mcp serve (D289)Copy Anchor Link

loams mcp serve serves MCP over stdio with rmcp (Apache-2.0; 3.5.0 on crates.io on 2026-10-01, and the workspace pins 3.4.1, so CLI1 Task 0 picks one) using the transport-io feature. It supports the same protocol versions as M1.6 Ruling 7: 2026-07-28 statelessly, and 2025-11-25, 2025-06-18 and 2025-03-26 with initialize. Stdout carries only JSON-RPC. Logs go to stderr at warn and to ~/.loams/logs/mcp.log at info. serverInfo is {"name": "loams", "version": "<binary version>"}. The tool list is fixed for the life of the process; it does not depend on which stacks exist.

Never MCP tools: stack stop, restart, delete, storage *, keys *, login, logout, configure, self-update, mcp install and uninstall, and anything with --from-source. The chat dump allowed destructive tools if they ask for confirmation. MCP 2026-07-28 replaces server-initiated requests (elicitation) with multi-round-trip input_required results (§15 §10), and client support for them varies, so this document omits destructive tools instead of relying on confirmation (D289). An agent that needs one asks the user to run the command.

Errors are CallToolResult::structured_error({"error": code, "message", "hint"}) with the same codes as §6.3, which follows M1.6 Task 7's error shape.

The data tools (search, sql, memory_write, list_collections, get_documents) are M1.6's HTTP server on the stack. They are not re-exported here, for four reasons:

• the tool list would otherwise change with stack state;
• the schemas would be duplicated;
• the stdio server would need loams-mcp and therefore the engine, which defeats the cli variant;
• one hop is better than two.

mcp install registers both servers instead (§12.2).

12.2 loams mcp install (D290)Copy Anchor Link

Rules:

• Absolute paths. GUI agents may not inherit the shell's PATH, so the entry always names the absolute binary path (~/.loams/bin/loams, expanded).
• Idempotent. Installing twice gives the same file. The CLI updates its own entries (named loams or loams-<stack>) and leaves every other entry, key and key order alone (serde_json with preserve_order, or toml_edit).
• Safe edits. The file is copied to <file>.loams-backup before the CLI's first edit to it. A file that does not parse is never rewritten (exit 5, config_unparseable). The write is atomic.
• Tracked. ~/.loams/mcp-installs.json records each entry written. mcp uninstall removes only those entries.
• --dry-run prints the command or a unified diff and writes nothing.
• --no-data skips the HTTP entry. The HTTP entry is also skipped, with a notice, when the stack has no mcp engine (before M1.6 merges, every stack).
• init detects agents by looking for claude and codex on PATH and for ~/.cursor/ and ~/.codeium/windsurf/, and offers to install for each one it finds.

13. Docs and snippets in the binary (D291)Copy Anchor Link

• Sources. docs/guides/**/*.md (user guides, starting with M1.6 Task 9's docs/guides/mcp.md, which this plan's Task 11 extends with a CLI guide) and docs/snippets/<engine>/<language>/<task>.<ext>. Each snippet starts with a front-matter comment block that lists packages, env and doc.
• The bundle. loams-cli's build.rs packs both trees into a zstd tarball and embeds it with include_bytes! (estimate: under 1 MB compressed). On the first search_docs call, the process builds an in-memory Tantivy index: title and body fields, the English stemmer, BM25. The index is never written to disk.
• The website and the bundle share one source. The product site in loam-cloud renders the same docs/guides (Q281 covers hosting). The binary therefore carries the docs of its own version, offline, and search_docs never disagrees with the installed server.
• Snippets are tested. A CI job, snippets (CLI1 Task 8), starts loams dev, sources a generated .env.loams, and runs every python and shell snippet (uv venv) and every typescript snippet (node 22). Each snippet asserts its own result. A snippet that does not run fails the build. Snippets that need packages that are not yet published (the SDKs before D33) run against the in-repo SDK sources.
• CLI1's first snippets: native, qdrant, es and pg × python, typescript and shell × connect, upsert and search. The mcp snippet is the .mcp.json entry itself.

14. Packages (D296, CLI2)Copy Anchor Link

release/packages.toml, embedded in the binary:

[sdk]
npm = "loams"            # D400; the `@loams` scope (D400) holds the other npm packages
pypi = "loams"
crates = "loams"
[bullmq]
npm = "@loams/bullmq"      # §26 §7.2
[celery]
pypi = "loams-celery"      # §26 §7.1
[durable]
npm = "@loams/durable"     # §26 §12.2
pypi = "loams"           # the helpers ship in the SDK (§26 §8.4)
[live]
npm = "@loams/live"      # R1 Task 14's package

• The ecosystem comes from --language, else from the project's files: pnpm-lock.yaml → pnpm add, bun.lock → bun add, yarn.lock → yarn add, package-lock.json or a bare package.json → npm install, uv.lock or a pyproject.toml with [tool.uv] → uv add, poetry.lock → poetry add, Cargo.toml → cargo add. A requirements.txt alone gets exit 6 with a hint (the CLI does not edit pip files). If more than one ecosystem matches, the CLI asks, or exits 3 without a TTY.
• The version is pinned to the CLI's minor version (loams@~0.4.0, loams>=0.4,<0.5, loams = "0.4"), so the SDK matches the server the CLI runs. --version overrides it.
• Anything not in the allow-list is refused from MCP (add_package). From the terminal, the CLI passes it through after a warning.

15. Keys, login and agents (D295, CLI3)Copy Anchor Link

• keys create calls the gateway's key API (part of the unified auth plan, D111, Q30) for one environment (§19 §5.5). The key defaults to a 90-day expiry. The CLI prints {key_id, token, expires_at} once in a terminal. With --write-env, it writes LOAMS_KEY_ID and LOAMS_API_KEY to the file and prints only key_id. For a local stack, the bootstrap key stack create makes is also kept in stacks/<name>/secrets/ (0600) so that env export can write it again. Keys for remote stacks are never stored by the CLI.
• login uses OAuth 2.1 authorization code with PKCE and a loopback redirect (RFC 8252) against the instance's authorization server (§19 §5.2, flow 2). Headless machines use the device flow (RFC 8628), if the auth plan adds it. Tokens go to credentials.toml (0600).
• mcp serve as an agent principal. mcp install registers an agent (§19 §5.1) owned by the user, with the policy collections:read, collections:write, query, mcp:tools on the profile's environment. mcp serve exchanges the user's credential for a vended agent token (§19 §5.2, flow 3), with a TTL of 15 minutes, on each call it makes to the stack. The user's credential stays in the CLI process and is never returned by a tool. Agents never hold API keys (§19 §5.5).
• Before the auth plan, keys and login exit 6 with auth_not_available and the hint "this build has no auth (D111); local stacks are loopback-only". .env.loams holds endpoints only.

16. Companions (D299, CLI3)Copy Anchor Link

The container runtime is Docker or Podman, whichever is found first; LOAMS_CONTAINER_RUNTIME overrides it. A companion's lifecycle follows its stack's (start, stop, delete). Companions are separate processes and never linked, so the license of the binary is unaffected.

17. DistributionCopy Anchor Link

17.1 The release pipeline (D292, CLI2)Copy Anchor Link

• cargo-dist 0.33.0 (released 2026-09-11; MIT OR Apache-2.0; active on 2026-10-01; verified). The workspace's dist-workspace.toml declares the following:

  Copy Text

  [dist]
  cargo-dist-version = "0.33.0"
  ci = "github"
  targets = ["x86_64-unknown-linux-gnu", "aarch64-unknown-linux-gnu", "aarch64-apple-darwin"]
  installers = ["shell"]                 # cargo-dist's own installer, published as a fallback
  checksum = "sha256"
  github-attestations = true
  hosting = "github"
  install-path = "~/.loams/bin"
  global-artifacts-jobs = ["./release-manifest"]   # runs in the build-global-artifacts phase; signs loams-release.json (verify that its outputs upload)
  [dist.github-custom-runners]
  x86_64-unknown-linux-gnu = "ubuntu-22.04"
  aarch64-unknown-linux-gnu = "ubuntu-22.04-arm"
  aarch64-apple-darwin = "macos-15"

• Variants. cargo-dist builds per package, with features and default-features per package (verified 2026-10-01). It does not offer several feature sets of one package. CLI2 Task 0 is a spike that tries thin variant packages: crates/loams-variant-standard and -full, each a two-line main.rs calling loams::main() with its own feature list and [[bin]] name = "loams". If cargo-dist's precise builds handle three packages that produce a binary of the same name, it builds all variants. If not, a Loams-owned matrix job in the same workflow builds the extra variants with cargo build -p loams --profile dist --features … and uploads loams-<variant>-<target>.tar.xz to the release (Q293).

• The release manifest, loams-release.json, is signed with minisign as loams-release.json.minisig:

  Copy Text

  {"schema": 1, "version": "0.4.0", "channel": "stable", "published_at": "2026-11-02T10:00:00Z",
   "output_schema": 1, "docs_version": "0.4.0",
   "artifacts": [{"variant": "standard", "target": "x86_64-unknown-linux-gnu",
     "url": "https://github.com/ostrium-labs/loams/releases/download/v0.4.0/loams-standard-x86_64-unknown-linux-gnu.tar.xz",
     "sha256": "…", "size": 0, "features": ["durable", "es", "flight", "hnsw", "mcp", "pgwire", "qdrant"]}]}

• Signing. The minisign secret key lives in the GitHub environment release, which has required reviewers (Q282). The public keys (current and next) are committed in release/minisign.pub and embedded in the binary and in install.sh. GitHub artifact attestations (Sigstore, SLSA build provenance) are verified out of band with gh attestation verify <file> --repo ostrium-labs/loams. A SHA256SUMS file is published for people who verify by hand.

• When. The pipeline runs on PRs as dist plan plus one dist build per target with publishing off. Publishing starts only after D33's rename PR and the transfer to ostrium-labs/loams (user memory). A release is cut by pushing a tag v<semver> on main.

17.2 install.sh (D293, CLI2)Copy Anchor Link

The source is release/install.sh: POSIX sh and set -eu, about 250 lines, checked by shellcheck. Each release publishes it with the version stamped in. https://loams.dev/install.sh answers 302 to https://github.com/ostrium-labs/loams/releases/latest/download/install.sh, and curl -fsSL follows the redirect. The GitHub URL works without loams.dev. loams.dev had no DNS record on 2026-10-01; the owner bought it on Cloudflare on 2026-10-02 (D401, answering Q281).

curl -fsSL https://loams.dev/install.sh | sh
curl -fsSL https://loams.dev/install.sh | sh -s -- --variant full --version 0.4.0 --yes --no-init

1. Platform. uname -s and uname -m give Linux x86_64/aarch64 or Darwin arm64. Anything else prints a message naming WSL2, cargo install, or the cli variant once it exists.
2. Tools. It uses curl (else wget), tar, xz and sha256sum (else shasum -a 256).
3. Manifest. It fetches loams-release.json (latest, or --version / LOAMS_VERSION). If minisign is installed, it verifies the signature with the embedded public key. If not, it says the signature was not checked and how to check it. --require-signature makes a missing minisign an error.
4. Archive. It downloads the archive for the variant (--variant, LOAMS_VARIANT, default standard) and target, and checks its SHA-256 against the manifest. A mismatch exits 9.
5. Install. It writes $LOAMS_HOME/bin/loams (LOAMS_HOME default ~/.loams) and the receipt receipt.json. It appends . "$HOME/.loams/env" to ~/.profile, ~/.bashrc and ~/.zshrc (those that exist) and adds ~/.config/fish/conf.d/loams.fish, unless --no-modify-path is given. A line is never added twice.
6. Init. If /dev/tty is readable (stdin is the pipe) and neither --no-init nor --yes was given, it asks "Run loams init now? [Y/n]" and reads the answer from /dev/tty.

Verification policy. The archive's SHA-256 check against the manifest is always mandatory. The manifest's signature is checked by install.sh only when minisign is installed, or always with --require-signature. This is the only verification path that may skip the signature, because a POSIX script has no portable Ed25519 verifier. Every download the binary makes (self-update, variant downloads) always verifies the signature (§17.3).

Trust model, stated in the guide. The first install trusts TLS and GitHub, which is the usual trust-on-first-use of curl | sh. From then on, the binary carries the public keys, so every self-update and every variant download is signature-checked whatever the host serves.

17.3 loams self-update (D294, CLI2)Copy Anchor Link

1. Refuse foreign installs. Without receipt.json, or when current_exe() is not $LOAMS_HOME/bin/loams, it exits 6 (managed_install) with the right upgrade command: cargo install loams (cargo install loam names an unrelated crate, verified 2026-10-01), or the package manager.
2. Fetch and verify the manifest for --version or the latest, with the embedded public keys (minisign-verify 0.3, MIT). A failure exits 9.
3. Check versions. If the target is not newer, it prints "up to date" and exits 0. --version with an older version needs --yes.
4. Download the archive for the receipt's variant (--variant switches it), then check its SHA-256 (exit 9 on mismatch).
5. Smoke-test. It extracts the archive to $LOAMS_HOME/bin/.loams-new and runs .loams-new version --output json. The version and features it reports must match the manifest.
6. Swap. It copies the current binary to bin/loams.prev, then self_replace::self_replace(".loams-new") (self-replace 1.5, Apache-2.0) swaps the binary atomically. It then updates the receipt.
7. Leave stacks alone. Running stacks keep their binary. stack describe shows binary_outdated and the hint loams stack restart --upgrade.
8. --check stops after step 3 and returns {current, latest, update_available}. --rollback swaps loams.prev back in.

axoupdater (cargo-dist's updater library, MIT OR Apache-2.0, 0.10.2) was considered. It updates from cargo-dist's own install receipts and installers, so it does not support Loams's variants or the minisign manifest. Self-replace plus minisign-verify is about 150 lines of Loams code.

18. TestingCopy Anchor Link

19. Roadmap: track CLI (D298)Copy Anchor Link

CLI1 runs beside M1, like tracks R and D: it adds one crate and three server flags, and changes no M1 code path beyond main.rs and the Native flag group. Its builds interleave with other tracks on the one-build machine (D127).

20. RisksCopy Anchor Link

21. Open questionsCopy Anchor Link

22. Contradictions with earlier decisions, and how they are resolvedCopy Anchor Link

23. SourcesCopy Anchor Link

Read on 2026-10-01.

• This repository at 9eaddae:
  • crates/loams/src/main.rs (the clap tree and the Native flags), crates/loams/Cargo.toml (features), crates/loams/src/api/mod.rs (/health, /ready), crates/loams-cache/src/range_cache.rs (RangeCacheConfig, DiskConfig), .github/workflows/ci.yml, Cargo.toml;
  • docs §04, §10, §15 §10, §19, §21, §26, §28; plans M1.6 (Rulings 7, 8, 11, 19; Task 9's client configs), PG1, R1; docs/open-core.md;
  • D29, D33, D58, D61, D65, D111, D124, D138, D220, D230, D231, D260, D262, D-PG-1;
  • the pending §29 (PR #172, D273–D280) for numbering.
• chatdump.md lines 1–51 (the owner's 2026-10-01 source).
• loam-cloud origin/main (2026-10-01): no MCP server; the brand names loams.dev; NEXT_PUBLIC_SITE_URL example https://loams.dev.
• cargo-dist: GitHub axodotdev/cargo-dist (releases v0.33.0 of 2026-09-11 and v0.32.0; license MIT OR Apache-2.0 in Cargo.toml; not archived; last push 2026-10-01). The config reference (features, default-features, checksum, install-path, installers, github-custom-runners, targets, hosting, min-glibc-version, github-attestations) and the customizing-CI page (the config keys plan-jobs, local-artifacts-jobs, global-artifacts-jobs, host-jobs, publish-jobs and post-announce-jobs; global-artifacts-jobs adds jobs to the build-global-artifacts phase, verified in the config reference's anchors on 2026-10-01) at axodotdev.github.io/cargo-dist.
• axoupdater: GitHub axodotdev/axoupdater (v0.10.2, 2026-08-12, MIT OR Apache-2.0).
• crates.io API (2026-10-01): minisign-verify 0.3.0 (MIT), self-replace 1.5.0 (Apache-2.0), clap 4.6.7, clap_complete 4.6.11, rmcp 3.5.0 (Apache-2.0), toml_edit 0.25.15, comfy-table 8.0.1, dialoguer 0.12.0, fs4 1.1.0, nix 0.31.3 (MIT); loams (2026-08-04, "File-based tree storage") and loams-cli (2025-01-22, "Loams CLI for building smart contracts") are taken; loams is free.
• npm registry and PyPI (2026-10-01): loams, @loams/sdk, @loams/bullmq and @loams/durable return 404 on npm; the @loams org lists no packages; loams is free on PyPI and loams is taken.
• DNS (2026-10-01): loams.dev does not resolve.
• Agent MCP configuration: code.claude.com/docs/en/mcp (claude mcp add [options] <name> -- <command>, scopes local, project and user, .mcp.json, CLAUDE_PROJECT_DIR); learn.chatgpt.com/docs/extend/mcp (Codex: ~/.codex/config.toml [mcp_servers.<name>] command, args, env; codex mcp add <name> -- <command>); cursor.com/docs/context/mcp (.cursor/mcp.json, ~/.cursor/mcp.json, type: "stdio"; no CLI); Windsurf: ~/.codeium/windsurf/mcp_config.json with mcpServers, command, args, serverUrl (from third-party guides at fast.io and grafana.com; verify against Windsurf's own docs in CLI1 Task 10).