---
title: Self-hosting
description: Run Shiplight tests on your own infrastructure with your own AI provider keys and persist local action cache across CI runs.
prev: false
next: false
---

# Self-hosting

<div class="view-markdown-wrapper">
<ViewMarkdown />
</div>

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](/local/local-testing/llm-providers#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:

```dotenv
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](/local/local-testing/llm-providers#choosing-a-model) for model and fallback settings, and [OpenAI-compatible endpoints](/local/local-testing/llm-providers#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:

```dotenv
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](/local/ci/action-cache):

- [CI cache storage](/local/ci/action-cache#option-1-github-actions-cache): restore before tests and save afterward, including when some tests fail.
- [Git persistence](/local/ci/action-cache#option-2-commit-cache-changes-to-git): 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:

```yaml
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.