Quick Start
Get Gostly running in a coffee break. By the end of this guide you'll have the proxy recording real API traffic and serving mocks — no code changes required.
Works in any environment
System requirements
Gostly's AI inference container needs ~6 GB free RAM (8 GB recommended). The proxy + dashboard add ~1 GB.
If you have less than 8 GB free, set ENABLE_GENERATION=false in your .env to run without AI inference (~1 GB total).
Docker Desktop's default 4 GB allocation will OOMKill the inference container — bump it to 8 GB in Docker Desktop preferences before running docker compose up.
Prerequisites
- → Docker and Docker Compose installed
- → A Gostly license key — get one free
- → Any HTTP service you want to mock (local, staging, or third-party — production access not required)
Setup
Authenticate with the image registry
From your dashboard, click Get registry token under Quick Start. Then run the login command it generates:
docker login -u AWS -p <your-registry-token> \ <your-registry-host>
Tokens are valid for 12 hours. You can refresh them from the dashboard at any time.
Download your compose file
The dashboard generates a docker-compose.yml pre-configured for your plan. Click Download docker-compose.yml or copy it directly. The compose file for a Pro/Team plan includes:
services: ghost-postgres: # local database ghost-web: # control plane API (port 8000) + dashboard (port 3000) ghost-inference: # AI inference engine (Pro/Team only) ghost-proxy: # HTTP proxy (port 8080) — the only thing your app talks to
Free tier includes ghost-proxy only.
Pin an image tag
The generated compose references :latest. For anything beyond a quick trial, pin a specific release tag (e.g. :v1.4.2) instead so a registry push can't change your stack out from under a pinned mock library or CI run.
Configure your upstream
Open the compose file and make two changes:
# Replace YOUR_LICENSE_KEY with the key shown on your dashboard GOSTLY_LICENSE_KEY: YOUR_LICENSE_KEY # Replace with the service you want to mock # This can be localhost, staging, a third-party API — anything HTTP BACKEND_URL: http://your-service:3000
BACKEND_URL is the upstream Gostly will forward to in LEARN mode and fall back to in PASSTHROUGH mode. It can be any reachable HTTP endpoint — a local dev server, a staging environment, or a public API.
Don't have a service to point Gostly at?
Run with the demo profile to use a bundled httpbin upstream:
docker compose --profile demo up
This starts a test API at http://demo-upstream:8080 with endpoints like /get, /post, and /status/404 you can record traffic against.
Start the stack
docker compose up -d
First run pulls several GB — plan for it
The first docker compose uppulls the images before anything starts. On Pro/Team that's the full AI stack — ~8–10 GB, typically 10–30 minuteson a home connection — with no progress bar beyond Docker's own layer output. It's a one-time download; subsequent starts are seconds. Free tier is ghost-proxy only — ~150 MB, under a minute.
The proxy starts in LEARN mode. Point your application at http://localhost:8080 instead of your upstream URL. Every request is forwarded and recorded automatically — no code changes needed.
On Pro/Team, the Gostly dashboard is at http://localhost:3000 — use it to watch traffic come in, manage services, and switch modes. Free tier ships the proxy only, so there is no local dashboard or control API — drive it with the curl commands shown in the steps below.
If your app speaks HTTPS
Set ENABLE_TLS_INTERCEPTION=true on the proxy and point your client at it with HTTPS_PROXY=http://localhost:8443. The proxy mints per-host leaf certs from an embedded CA — fetch and trust it once:
curl http://localhost:8080/ca.crt > gostly-ca.crt # then add gostly-ca.crt to your client/OS trust store
See Proxy Setup → TLS for the per-OS trust-install steps and the Caddy-fronting alternative. Plain ws:// is captured; wss:// interception is not yet supported.
Generate traffic
Run your test suite, exercise your app manually, or replay a traffic capture. Gostly records every request-response pair. You can see what's been captured in the dashboard or via the API:
curl http://localhost:8000/mocks \ -H "X-API-Key: $GHOST_API_KEY" | jq '.count'
The shipped compose runs the control plane fail-closed: once GHOST_API_KEY is set in your .env, every control-plane call on port 8000 needs the X-API-Key header. (In a throwaway local trial with GHOST_API_KEY unset the API is permissive and the header is optional.)
The more traffic you record, the more complete the mock library becomes. There's no minimum — even a handful of interactions is enough to start replacing upstream calls in CI.
Switch to MOCK mode
Once you have traffic recorded, flip to MOCK mode from the dashboard at http://localhost:3000 (Pro/Team), or via the API — the only path on Free tier, which ships no dashboard:
curl -X POST 'http://localhost:8000/v1/mode?mode=MOCK' \ -H "X-API-Key: $GHOST_API_KEY"
Or, equivalently, send the mode as a JSON body:
curl -X POST http://localhost:8000/v1/mode \
-H "X-API-Key: $GHOST_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"mode": "MOCK"}'Your app keeps talking to http://localhost:8080. Responses are now served from the recorded library — instant, deterministic, and requiring zero network connectivity to the upstream.
Sharing mocks across environments
Before committing ./data/ — read this
./data/mocks/ and ./data/traffic/ contain verbatim HTTP response bodies exactly as returned by the upstream. If the upstream returns emails, tokens, or any user data, those values are in these files. Add both to .gitignore by default and only commit after deliberately reviewing the contents.
./data/mode.txt and ./data/machine_id contain no sensitive data and are safe to commit. ./data/license_cache.json contains your license JWT — omit it.
If you're recording against a local dev server with no real user data, committing./data/mocks/ is a practical way to share a mock library across environments. Add a safe .gitignore:
# .gitignore — safe defaults for Gostly data directory data/traffic/ # raw append-only traffic log — never commit data/license_cache.json # Only commit data/mocks/ if you've confirmed it contains no PII # data/mocks/ ← uncomment to exclude
For CI, mount the committed mock directory and start the proxy in MOCK mode. The proxy runs standalone — ghost-web is not required to serve mocks:
# docker-compose.ci.yml — proxy only, no dashboard needed
services:
ghost-proxy:
image: <your-registry-host>/gostlyai/proxy:latest
ports:
- "8080:8080"
environment:
GOSTLY_LICENSE_KEY: ${GOSTLY_LICENSE_KEY}
BACKEND_URL: http://your-service:3000
INITIAL_MODE: MOCK # start in mock mode without a mode.txt
MOCK_DIR: /data/mocks
MODE_FILE_PATH: /data/mode.txt
volumes:
- ./data:/data:ro # read-only — CI never writes new traffic