Self-hosting

View as Markdown

Run the Shiplight CLI and browsers on your own machine or CI runners, bring your own AI provider key (BYOK), and keep action cache and test reports in storage you control. This setup requires no Shiplight account or API token.

1. Bring your own key

Follow Bring your own key to choose a provider. Put its key in your project's ignored .env file, or inject it through your CI secret store. For example:

GOOGLE_API_KEY=your-google-api-key
WEB_AGENT_FALLBACK_MODELS=
SHIPLIGHT_TELEMETRY=0

Remove SHIPLIGHT_API_TOKEN from both .env and the runner environment for this setup. The provider bills AI usage to your account. The empty WEB_AGENT_FALLBACK_MODELS disables the built-in cross-provider fallback chain; SHIPLIGHT_TELEMETRY=0 disables the CLI's anonymous usage telemetry.

See Choosing a model for model and fallback settings, and OpenAI-compatible endpoints to connect your own model service. BYOK sends the page context needed for AI actions to your selected provider.

2. Persist local action cache in CI

Set the local backend explicitly:

SHIPLIGHT_ACTION_CACHE_BACKEND=local

This keeps actions in .shiplight/action-cache/, even in CI with a Shiplight token. Persist that directory between runs using one of the workflows in Action cache in CI:

• CI cache storage: restore before tests and save afterward, including when some tests fail.
• Git persistence: track cache JSON in your repository and commit updates from CI.

Those examples use a Shiplight token for AI calls. For BYOK, replace their job-level env block with:

env:
  GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
  SHIPLIGHT_API_TOKEN: ""
  SHIPLIGHT_ACTION_CACHE_BACKEND: local
  WEB_AGENT_FALLBACK_MODELS: ""
  SHIPLIGHT_TELEMETRY: "0"

Add GOOGLE_API_KEY to your CI secret store, or substitute your chosen provider's key. Project .env values override workflow values, so remove conflicting settings there too.

The linked workflows use GitHub-hosted ubuntu-latest. To execute on your own registered Linux runner, change runs-on to [self-hosted, linux, x64] and ensure it has the browser dependencies and network access your tests need. GitHub cache storage still lives on GitHub; use your internal cache service if all storage must remain on your infrastructure.

Keep test reports in your CI artifacts or internal storage by preserving shiplight-report/ and test-results/. Omit npx shiplight report to avoid uploading results to Shiplight Cloud.