# LightShip

- [LightShip](https://lightship.mintlify.app/index.md): Give humans and coding agents policy-controlled access to OpenTelemetry traces.
- [Quickstart](https://lightship.mintlify.app/quickstart.md): Start LightShip against your existing ClickHouse, sign in as admin, bind the trace table, and run your first authorized query.
- [Install LightShip](https://lightship.mintlify.app/get-started/install.md): Run LightShip with Docker Compose or build the lightship binary from source.
- [Authentication](https://lightship.mintlify.app/get-started/authentication.md): Sign in to LightShip with username and password for the web UI, or use personal API keys with Bearer tokens for MCP and REST automation.
- [Architecture](https://lightship.mintlify.app/concepts/architecture.md): How LightShip sits between agents, the UI, and your ClickHouse trace store, and how a request becomes an authorized result.
- [Access Model](https://lightship.mintlify.app/concepts/access-model.md): The LightShip access model binds a ClickHouse trace table, marks fields as filterable or policy inputs, and assigns roles and attributes to users.
- [Policies](https://lightship.mintlify.app/concepts/policies.md): LightShip role policies are CEL expressions over marked trace fields and user attributes. Learn the supported operators, worked examples, and validation rules.
- [Audit Log](https://lightship.mintlify.app/concepts/audit.md): See which authentication, query, and configuration activity LightShip records.
- [Connect Trace Data](https://lightship.mintlify.app/configure/discover-trace-source.md): Choose the table that contains your traces and the fields users can search or use in access rules.
- [Define Roles](https://lightship.mintlify.app/configure/roles-and-policies.md): Review existing access and build roles from trace fields, operators, and user attributes.
- [Manage Users](https://lightship.mintlify.app/configure/users.md): Create users and assign roles in the web UI; manage access-rule attributes through the admin API.
- [Configure Tenant-Scoped Trace Access](https://lightship.mintlify.app/guides/tenant-scoped-trace-access.md): Connect a shared ClickHouse trace table, create a tenant-scoped role, and verify the access boundary.
- [Use the Web UI](https://lightship.mintlify.app/use/web-ui.md): Use the LightShip web UI to browse traces, manage API keys, complete guided setup, and review audit logs.
- [Connect LightShip MCP](https://lightship.mintlify.app/use/mcp.md): Connect an AI client to LightShip for trace investigation.
- [Configuration](https://lightship.mintlify.app/operate/configuration.md): Configure LightShip with environment variables for ClickHouse, Postgres, caching, resource limits, and admin credentials.
- [Admin Recovery](https://lightship.mintlify.app/operate/admin-recovery.md): Recover the LightShip admin account if the generated password is lost. Generate a new hash with the CLI and rotate it safely without losing data.
- [Deployment](https://lightship.mintlify.app/operate/deployment.md): Deploy LightShip securely as a containerized HTTP service backed by Postgres and a read-only ClickHouse connection.
- [CLI Reference](https://lightship.mintlify.app/operate/cli.md): Reference for serving LightShip, connecting coding agents, validating the access model, and generating password hashes.
- [Limitations](https://lightship.mintlify.app/operate/limitations.md): Review current LightShip limitations for authorization, authentication, schema handling, querying, and operational controls.
- [REST API](https://lightship.mintlify.app/api-reference/introduction.md): The LightShip REST API accepts JSON, uses session cookies for browsers and Bearer keys for automation, and applies role policies on every request.
- [Trace Filters](https://lightship.mintlify.app/api-reference/filters.md): Build trace filter conditions in LightShip using structured operators. Learn the exact JSON form, valid operators per logical type, and how filters map to role policies.
- [Errors](https://lightship.mintlify.app/api-reference/errors.md): Reference for LightShip REST error responses. Includes status codes, fail-closed behavior, and how policy compile and ClickHouse errors surface to callers.
- [POST /login](https://lightship.mintlify.app/api-reference/identity/login.md): Authenticate a browser user with username and password. Returns a session cookie used on subsequent requests until logout or password change.
- [POST /logout](https://lightship.mintlify.app/api-reference/identity/logout.md): Delete the current browser session in LightShip. The next request without a valid session cookie or Bearer key is rejected.
- [GET /me](https://lightship.mintlify.app/api-reference/identity/me.md): Return the authenticated caller's identity, roles, preview state, and account flags.
- [POST /me/password](https://lightship.mintlify.app/api-reference/identity/change-password.md): Change the authenticated user's password. Clears must_change_password and revokes the caller's other browser sessions across all replicas.
- [API Keys](https://lightship.mintlify.app/api-reference/identity/keys.md): Create, list, and revoke personal LightShip API keys. Tokens are shown once at creation and carry the creator's roles by reference on every request.
- [POST /traces/query](https://lightship.mintlify.app/api-reference/traces/query.md): Query authorized OpenTelemetry trace spans in LightShip with a time range, structured filter, limit, and cursor. Streams JSON and supports cursor-based pagination.
- [GET /traces/{id}](https://lightship.mintlify.app/api-reference/traces/get.md): Fetch one authorized trace by its trace ID. LightShip applies role policies to the trace as a whole and fails closed if the caller is unauthorized.
- [GET /filter/schema](https://lightship.mintlify.app/api-reference/traces/filter-schema.md): Return the fields the caller may filter on, their logical types, and compatible operators.
- [Schema API](https://lightship.mintlify.app/api-reference/access/schema.md): Admin REST endpoints for the LightShip access model: discover ClickHouse tables, export the model, bind the trace source, mark fields, and review DDL suggestions.
- [Roles API](https://lightship.mintlify.app/api-reference/access/roles.md): Create, replace, and delete LightShip roles through the admin REST API. Each role carries CEL policy expressions over marked trace fields and user attributes.
- [Users API](https://lightship.mintlify.app/api-reference/access/users.md): Admin REST endpoints for LightShip users. Create accounts with generated passwords, assign roles and attributes, rotate passwords, and delete users with sessions.
- [GET /audit](https://lightship.mintlify.app/api-reference/audit.md): Read the LightShip audit log through the admin REST API. Records authentication, trace queries, and configuration changes, with in-process retention pruning.
- [LightShip MCP Connections](https://lightship.mintlify.app/api-reference/mcp.md): Tool groups and configuration for the everyday LightShip MCP and administrator Setup connection.