Skip to main content
The lightship binary provides the HTTP service, local MCP companion, access-model check, and password-hashing utility. Every command exits with a non-zero status on failure. Run Docker Compose examples from the LightShip checkout root.

​
Command summary

​
lightship serve

serve is the command you run in production and in local development. On startup it performs the following actions in order:
  1. Connects to Postgres using DATABASE_URL.
  2. Runs any pending schema migrations.
  3. Creates the admin account if LIGHTSHIP_ADMIN_PASSWORD_HASH is set, or generates a one-time password, prints it to the log, and stores its hash.
  4. Loads the access model into memory.
  5. Starts the HTTP server on the address given by LIGHTSHIP_ADDR (default :8080).
Example invocation:
serve requires both DATABASE_URL and CLICKHOUSE_DSN. An invalid or unreachable Postgres connection, or a malformed ClickHouse DSN, prevents startup. If a valid ClickHouse endpoint is temporarily unreachable, LightShip starts but trace queries fail closed until it recovers.

​
lightship mcp

mcp is launched by a coding agent as a local stdio server. It provides LightShip’s bounded trace tools and lightship_export_traces. The export tool follows REST pagination and writes a complete JSONL artifact under .lightship/exports without returning its rows through MCP. Keep the export directory out of version control because it can contain complete trace payloads. See MCP Clients for client configuration.

​
lightship check

check validates the stored access model without starting a server or altering the database. Use it in CI pipelines or before rolling out a configuration change to confirm that roles and policies compile correctly. It does not verify that your ClickHouse schema matches the bound source. Example invocation:
A missing source binding produces a warning, not a fatal error, so check can be used on a fresh database before setup is complete.

​
lightship hash

hash generates an Argon2id hash from a password. Use it to precompute LIGHTSHIP_ADMIN_PASSWORD_HASH or to rotate the admin password securely. LightShip accepts only this fixed profile: v19, 64 MiB memory, 3 iterations, 4 lanes, a 16-byte salt, and a 32-byte digest, in canonical PHC encoding. Other profiles and malformed encodings are rejected before storage and verification. Replace any previously imported hash that uses another profile with one generated by this command before upgrading. Example invocation with a hidden terminal prompt:
Example invocation piping a password from stdin:
lightship hash does not connect to Postgres or ClickHouse, so it can run offline or inside a restricted container.

​
Next steps

  • For recovering the admin account when the password is lost, see Admin Recovery.
  • For the full list of environment variables, see Configuration.