Proxy Setup

Basic single-service setup

Start with the Compose file and environment template from your account dashboard. The licensed Free stack includes the proxy, local dashboard/control API, Postgres, and the one-shot migration service. Keep those dependencies intact. See Install & Deploy for environment and authentication setup. Once the stack is ready, register one upstream using a matching host or path rule, as shown below:

TLS for HTTPS environments

For HTTPS interception, enable the listener in the proxy environment and publish port 8443 in its Compose configuration if it is absent. Trust the proxy CA in your test client. You can also terminate TLS at the edge: The agent can terminate TLS itself by setting ENABLE_TLS_INTERCEPTION — a CONNECT forward proxy on port 8443 that mints per-host certificates from an embedded CA (clients fetch the CA from /ca.crt). Or, if you prefer to terminate TLS at the edge, front the proxy with Caddy, which handles TLS and forwards to Gostly over plain HTTP:

# Caddyfile
mock.internal.example.com {
  reverse_proxy ghost-proxy:8080
}

services:
  caddy:
    image: caddy:2-alpine
    ports:
      - "443:443"
      - "80:80"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy-data:/data
    depends_on:
      - ghost-proxy

  ghost-proxy:
    image: <your-registry-host>/gostlyai/proxy:latest
    container_name: ghost-proxy
    # Do NOT expose port directly — traffic comes through Caddy
    environment:
      GOSTLY_LICENSE_KEY: "YOUR_LICENSE_KEY"
      BACKEND_URL: "https://api.example.com"
      MOCK_DIR: /data/mocks
      MODE_FILE_PATH: /data/mode.txt
    volumes:
      - ./data:/data

Multiple upstream services

A single ghost-proxy instance handles multiple upstream services simultaneously. You register each service via the API with a routing rule — either host-based (matched on the Host request header) or path-based (matched on a URL prefix). Each service gets its own mock library, mode, chaos config, and redaction rules.

Register services after the stack is running. The control plane runs fail-closed, so every call on port 8000 carries the X-API-Key header (the value of GHOST_API_KEY from your .env):

# Host-based routing — route by the Host header your app sends
curl -X POST http://localhost:8000/services \
  -H "X-API-Key: $GHOST_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name":          "payments",
    "upstream_url":  "https://payments.internal",
    "routing_type":  "host",
    "routing_value": "payments.internal"
  }'

# Path-based routing — route by URL prefix
curl -X POST http://localhost:8000/services \
  -H "X-API-Key: $GHOST_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name":          "users",
    "upstream_url":  "https://users.internal",
    "routing_type":  "path",
    "routing_value": "/api/users"
  }'

Wait for the configured service to synchronize to the proxy before recording; resolve missing-upstream or authentication errors first. Requests that don't match any registered service fall through to BACKEND_URL (the default upstream configured at startup).

After recording, build the service library and wait for the build to complete without errors. Each service can then be switched to a different mode independently:

# Switch one service to MOCK while others stay in LEARN
curl -X PUT http://localhost:8000/services/{service_id} \
  -H "X-API-Key: $GHOST_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"mode": "MOCK"}'

# Or switch the global mode for all services at once
curl -X POST http://localhost:8000/v1/mode \
  -H "X-API-Key: $GHOST_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"mode": "MOCK"}'

CI integration

Reuse the generated stack with pinned images, a reviewed test library, and the same service routing configuration used to build it. Supply registry access and installation credentials through your CI secret store. Registry pulls and license validation have separate connectivity needs from replay; do not assume the entire installation process is offline.

1. Start the complete stack and wait for database setup and service configuration to finish.
2. Confirm the intended library loaded, choose MOCK explicitly, and check readiness before running application tests.
3. Run one known request and verify its status/body and that the upstream request count stays unchanged.
4. Run your test suite against the proxy, then stop the disposable CI stack while preserving any evidence you need.

Chaos injection

Chaos config is applied per service and can be updated at runtime without restarting the proxy. Useful for resilience testing:

# Enable chaos for a specific service
curl -X PUT http://localhost:8000/services/payments/chaos \
  -H "X-API-Key: $GHOST_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "enabled": true,
    "error_rate": 0.05,        // 5% of requests return a 500
    "latency_ms_min": 50,
    "latency_ms_max": 300,
    "inject_status": null       // or e.g. 429 to always return rate-limit
  }'