Self-hosting

Skipperu is a React app backed by a small stateless .NET proxy. There are no accounts and no server database. Everything you save lives in your browser’s IndexedDB, and the backend only proxies requests and imports OpenAPI specs.

Docker

The prebuilt image is ghcr.io/godwindev1/skipperu. It is built for linux/amd64.

docker run -p 127.0.0.1:5757:5757 ghcr.io/godwindev1/skipperu:latest

Open http://localhost:5757.

To build the image yourself:

docker build -t skipperu .
docker run -p 127.0.0.1:5757:5757 skipperu

Single-file executable

Build the executable for your OS with scripts/publish-backend.sh, then run it from any directory:

./Skipperu

Open http://localhost:5757.

Desktop app

The Windows installer bundles everything. Download it from the releases page. The installer is unsigned, so SmartScreen will warn you on first run.

From source

cd Skipperu.Web && npm ci && npm run build
cd ../Skipperu.backend && dotnet run

dotnet run serves the built React app from wwwroot alongside the API. See Contributing for the development setup.

Configuration

Set these as environment variables (Skipperu__<Name>), or in appsettings.json under a Skipperu section.

Variable	Default	Description
Skipperu__Host	localhost	Address to bind to. Change it only if you understand the token requirement below.
Skipperu__Port	5757	Port to bind to.
Skipperu__Token	empty	If set, every /api/* request except /api/health must send it in the X-Skipperu-Token header.
Skipperu__TimeoutSeconds	30	Timeout for outbound proxy requests and OpenAPI spec fetches.
Skipperu__MaxResponseBytes	10485760	Response bodies larger than this are truncated (truncated: true in the response).

Access token

By default Skipperu binds to localhost only, so other machines cannot reach it. If you bind it to a non-loopback address (0.0.0.0 in Docker, or a LAN IP) without a token, anyone who can reach that host can use your proxy. The app logs a startup warning in that case.

Caution

Skipperu__Token is required whenever you expose Skipperu beyond your own machine: Docker with a non-loopback published port, a LAN IP, a reverse proxy, and so on. Also put it behind HTTPS, since the token is sent in a header.

docker run -p 5757:5757 -e Skipperu__Token=<a-long-random-secret> ghcr.io/godwindev1/skipperu:latest

Canonical origin

Browser storage is per origin. localhost and 127.0.0.1, or the same host on a different port, are separate, unrelated workspaces. Pick one address and keep using it.

Way of running	Origin
Docker, executable, from source	http://localhost:5757
Desktop app	http://127.0.0.1:48757

The desktop app’s port can be changed with the SKIPPERU_DESKTOP_PORT environment variable, but saved data is per port.

Backups

Nothing is backed up automatically. Use Export in the app to save a JSON file, and Import to restore it with Merge or Replace. This is also how you move your data to another browser or machine.

Note

Exports contain your environment variables in plain text. Treat the file like a secret if your variables hold tokens or keys.