Install & Deploy

What you're installing

The licensed product is delivered as a docker-compose.yml plus a set of pre-built images. You authenticate to the image registry with a short-lived token from your dashboard, pull the images, fill in an .env, and run docker compose up. A Pro/Team stack is five services on a shared ./data bind-mount:

The Free tier ships ghost-proxy only — no inference, no dashboard. The proxy serves recorded mocks standalone and never needs the rest of the stack to replay.

Prerequisites

• → Docker and Docker Compose installed (Docker Desktop, or Docker Engine + the Compose plugin on Linux)
• → A Gostly license key — get one free. The key gates which tier capabilities the stack unlocks.
• → A registry login token (issued from your dashboard, valid 12 hours) to pull the images
• → Any HTTP service you want to mock — local, staging, or third-party. Production access is not required.

System sizing

The memory footprint is dominated by one container. The proxy, dashboard, and database are light; the AI inference engine is what sets your floor. Plan for two numbers:

The compose file sets the inference container's memory limit via INFERENCE_MEM_LIMIT and pins its CPU with INFERENCE_CPU_LIMIT. The PyTorch BLAS thread count is INFERENCE_NUM_THREADS — set it relative to your core count (the shipped .env.example carries per-machine recommendations). Keep INFERENCE_CPU_LIMIT ≥ INFERENCE_NUM_THREADS or the thread pool starves.

Low-memory path — run without AI generation

If you have less than 8 GB free, run the stack without the generative model loaded. The match cascade stays fully functional — exact match, session-verbatim replay, the statechart / resource engine, and smart swap all run with no model in memory. You only lose the last-resort AI-generation fallback for requests that match nothing recorded.

# In .env — skip loading the generative model
ENABLE_GENERATION=false

With generation off, the inference container does not load the base model, and the whole stack runs in roughly ~1 GB total. Retrieval (ENABLE_RAG) is a separate, lighter knob and is on by default — it loads only the sentence-encoder, not the generative model. On a truly memory-constrained machine you can set ENABLE_RAG=false as well.

Ports

Three ports are published to the host on a Pro/Team stack. Postgres, inference, and the generation sidecar stay on internal Docker networks and are never exposed.

On HTTPS, fetch and trust the proxy's MITM CA once — it serves the cert at GET /ca.crt on port 8080 (which returns 503 while interception is off, so flip the knob first):

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.

.env setup

All configuration is environment variables — there are no runtime config files. Copy the example file and fill in the four things that have no safe default:

cp .env.example .env

The sizing and feature knobs you'll most often touch at install time:

# Sizing — see System sizing above
INFERENCE_MEM_LIMIT=10G       # inference container memory limit
INFERENCE_CPU_LIMIT=4         # must be >= INFERENCE_NUM_THREADS
INFERENCE_NUM_THREADS=4       # PyTorch BLAS threads — tune to core count

# AI behaviour
ENABLE_GENERATION=false       # set true to load the generative model (needs the RAM)
ENABLE_RAG=true               # retrieval — light; on by default

# Tenant identity (single-tenant deployments typically pin this)
GOSTLY_TENANT_ID=default

# Optional: enable TLS interception on :8443 (off by default)
ENABLE_TLS_INTERCEPTION=false

Pulling the images

The licensed images live in a private registry. From your dashboard, click Get registry token under Quick Start to generate a login command. The token is valid for 12 hours; refresh it any time.

# The dashboard generates this with your registry host filled in
docker login -u AWS -p <your-registry-token> <your-registry-host>

# Then pull and start the stack
docker compose pull
docker compose up -d

The dashboard also generates a docker-compose.yml pre-configured for your plan — download it or copy it directly. The Free tier compose references ghost-proxy only; Pro/Team include the inference engine, dashboard, and database.

First boot

On docker compose up -d the proxy starts in LEARN mode (override with INITIAL_MODE). Point your application at http://localhost:8080 and every request is forwarded to your upstream and recorded — no code changes needed. Open the dashboard at http://localhost:3000 to watch traffic arrive and switch modes.

To skip pointing at a real upstream and start with a seed instead, drag a HAR, Postman collection, or OpenAPI spec onto the dashboard — it posts to the cold-start importer:

POST /v1/seed/har      # also: /v1/seed/postman, /v1/seed/openapi

The inference container's first /generate call after startup may briefly return 503 while the model loads (only relevant when generation is enabled). From there, drive the LEARN → MOCK pipeline as described in Quick Start.

Metrics & health

Each service exposes a /health endpoint used by the compose healthchecks. The proxy also exports Prometheus metrics at /metrics for scraping into your own monitoring: