Install LightShip

Run LightShip with Docker Compose or build the lightship binary from source.

LightShip runs as a single Go binary or container. Docker Compose is the fastest local evaluation path; hosted deployments can run the same container or binary alongside Postgres.

Install the lightship command

Download the latest experimental archive and SHA256SUMS from GitHub Releases. Verify the checksum, unpack the archive for your platform, and place the lightship binary on your PATH.

If you have Go 1.25 or newer, you can instead install directly from the module:

go install github.com/lightshipHQ/lightship/cmd/lightship@v0.1.0-alpha.1
export PATH="$(go env GOPATH)/bin:$PATH"

Add the export PATH=... line to your shell profile if lightship is not found in a new terminal. The command is now available as lightship; continue to MCP Clients to connect a coding agent.

The release also publishes a multi-platform container image:

docker pull ghcr.io/lightshipHQ/lightship:v0.1.0-alpha.1

Docker Compose

The Compose stack runs LightShip and a Postgres instance for its own state (access model, users, keys, audit). It does not include ClickHouse: LightShip reads traces from a ClickHouse you already run.

1. Clone the repository

   Run these commands from a directory that does not already contain a file or directory named lightship. Skip this step if you are already in a LightShip checkout.

   git clone https://github.com/lightshipHQ/lightship.git && cd lightship
   
2. Configure the environment

   Copy the example file and set CLICKHOUSE_DSN to a read-only connection string for your trace database.

   cp .env.example .env
   
3. Start the stack

   docker compose up -d
   docker compose logs control-plane
   

   The first-boot admin password is printed once to the control-plane log.

4. Open the web UI

   Visit http://localhost:8080 and sign in as admin.

See the Quickstart for a walkthrough that ends with a bound trace source.

Native binary

Run lightship serve directly when you manage Postgres yourself. It applies Postgres migrations, initializes the admin account, loads the access model, and starts the HTTP server for REST, MCP, and the UI.

Required environment:

• DATABASE_URL: Postgres connection string.
• CLICKHOUSE_DSN: read-only ClickHouse connection string.

DATABASE_URL=postgres://... \
CLICKHOUSE_DSN=https://user:[e-mail]:8443/db?secure=true \
  lightship serve

For every command and environment requirement, see the CLI reference and Configuration.

Next steps

Authenticate

Get a personal API key or sign in with the admin session.

Bind your trace source

Point LightShip at your ClickHouse trace table.