LightShip

LightShip

Faster production-agent iteration, without a developer bottleneck.

[CI] [Release] [Container] [License]

LightShip gives domain experts governed, self-serve access to production agent traces. It sits in front of your existing OpenTelemetry data in ClickHouse, so humans and AI coding agents can investigate real conversations and tool calls without database credentials or another observability silo.

Documentation · Website · Contribute

Why LightShip

• Find the patterns behind failures. Ask business questions across conversations, tool calls, and outcomes using Codex, Claude, or another MCP client.
• Keep your existing trace store. Bind LightShip to your OpenTelemetry table without copying traces into a separate platform.
• Instrument once; define policies later. Select existing columns and attribute keys as authorization inputs, then create or change policies without re-instrumenting. The same policy governs the web UI, REST API, and MCP.
• Keep large investigations out of model context. The local MCP companion writes authorized exports into the agent workspace and returns only paths and counts to the conversation.

How it works

1. An administrator binds LightShip to an existing OpenTelemetry span table in ClickHouse.
2. They choose which columns and map keys may be used for search and access rules.
3. LightShip compiles each caller’s roles and attributes into the ClickHouse query before returning any trace through the web UI, REST, or MCP.

A trace is the authorization unit: one matching span grants access to the complete trace. LightShip never gives restricted users direct ClickHouse credentials.

Performance

Query performance depends on the layout and indexes of your existing ClickHouse trace table. After you select the fields available to filters and access policies, LightShip reviews the table's sorting key and skip indexes and suggests DDL for missing indexes. These recommendations are advisory: LightShip never changes your ClickHouse schema automatically. See how to review the optimization report.

Get started

The documentation contains the maintained setup and reference material:

• Install the latest alpha
• Browse the Go package
• Connect your ClickHouse
• Define roles and policies
• Connect Codex, Claude, and other MCP clients
• Use the web UI
• Deploy and configure LightShip
• Browse the API reference

Need help deploying LightShip in your environment? Talk to us.

Security and project status

LightShip protects only requests sent through LightShip. Direct ClickHouse access bypasses its policies. It does not currently detect PII, redact payloads, or hide individual spans. Query auditing is best-effort, so an audit-write failure is logged without failing the trace request.

LightShip is an experimental alpha with no stable release. Evaluate it using synthetic or non-sensitive data in an isolated environment. Read the security guidance and current limitations before deployment.

Feedback

We want to help make autonomous work trustworthy and governable. If your team operates AI agents in production, we would love to hear what LightShip should support next.

Talk to us or open a GitHub issue.

Contributing

See CONTRIBUTING.md for development and testing, SECURITY.md for vulnerability reporting, and CHANGELOG.md for changes. LightShip is licensed under Apache-2.0.