Getting Started

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

Gostly doesn't need production access. Point it at any upstream — localhost, a staging server, a shared dev environment. Traffic learned in one environment can be committed and replayed in any other, including fully offline on a laptop.

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> \
  &lt;your-registry-host&gt;

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.

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

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.

The Gostly dashboard is at http://localhost:3000 — use it to watch traffic come in, manage services, and switch modes.

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 | jq '.count'

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, or via the API:

curl -X POST 'http://localhost:8000/v1/mode?mode=MOCK'

Or, equivalently, send the mode as a JSON body:

curl -X POST http://localhost:8000/v1/mode \
  -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.

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: &lt;your-registry-host&gt;/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

What's next

How It Works →

Understand the LEARN → MOCK pipeline and how AI fills gaps.

Proxy Setup →

Advanced config: multiple services, TLS, CI integration, chaos injection.

Configuration →

Full reference for every environment variable and option.