# Gostly — full ingest > Long-form companion to /llms.txt. Each page below is followed by a multi-paragraph summary suitable for direct ingestion by an AI codegen tool. For the canonical version of any page, follow the linked URL or fetch the `.md` form (e.g. /docs/quickstart.md). ## Pages ### Gostly URL: https://gostly.ai/ Gostly is an HTTP proxy that learns from real upstream traffic and replays it as deterministic, tenant-isolated mock responses. It removes the need to hand-write API stubs. Four operating modes: LEARN forwards every request to the upstream and records the response; MOCK serves from the recorded library with no upstream contact; PASSTHROUGH proxies without recording; TRANSITIONING is the controlled hand-off between modes. The match cascade prefers cheap, deterministic strategies before reaching for AI: exact match first, then in-session verbatim replay (RAM-only, byte-exact bodies and headers), then statechart-driven resource transitions (so POST then GET of the same resource returns it, not a 404), then structural smart-swap of variable fields, then (on Pro and Team tiers) AI generation only at the edge as a last resort — for requests with no matching capture. AI is opt-in for Pro+ tiers; it is not on the hot path for Free deployments. Security is structural. The credential-header floor (Authorization, Cookie, every X-Api-Key variant) is stripped at the moment the proxy reads the request — before recording, before logging, before disk. Request and response bodies are kept byte-verbatim in the on-disk replay library by design (exact-fidelity replay is the value prop); the 19-category regex scrub — tokens, payment cards, government IDs, contact information — runs over the Postgres-backed mock library that feeds the dashboard, training, and every export, so all shipped and exported data is structurally scrubbed. Tenant isolation runs in Postgres Row-Level Security, not just in application WHERE clauses. SSRF protection on webhook replay refuses loopback, RFC1918, link-local, cloud instance-metadata, and eight blocked service ports. ### Use cases URL: https://gostly.ai/use-cases Concrete development and testing scenarios Gostly is built for. Cold-start CI without upstream credentials: record traffic once against staging, commit the scrubbed mock library, run integration tests against the proxy with zero outbound network. Deterministic test environments: flip to MOCK mode and the same recorded library produces the same response on every run. Offline replay: a developer on a flight or in a regulated environment can run the full app stack against a recorded library, no upstream reachable. ### Architecture URL: https://gostly.ai/architecture How the Gostly stack fits together: agent (Rust HTTP proxy), API (Python control plane), inference server, and dashboard. All self-hosted; only telemetry counters and license issuance reach Gostly's cloud. ### Security URL: https://gostly.ai/security Structural security invariants by construction: REDACT_FLOOR header stripping at capture, per-tenant Postgres RLS, customer self-hosted deployment with no payload data leaving the customer's infrastructure. ### Clean-room runbook for Claude Skills URL: https://gostly.ai/features/clean-room Step-by-step runbook for wiring Claude Skills against Gostly-served mocks instead of live upstream APIs. Capture real traffic, switch to mock mode, point your skill at the local proxy — deterministic, sealed, auditable by construction. ### Agent runtime URL: https://gostly.ai/features/agent-runtime Gostly as the deterministic agent runtime layer: byte-equivalent upstream replay, pre-execution policy gate, and cryptographically logged decision trace around AI agent tool calls. Self-hosted; no LLM in the request hot path. ### Partners URL: https://gostly.ai/partners Integration and reseller partners for Gostly, with focus on regulated and latency-sensitive verticals. ### Test AI agents URL: https://gostly.ai/test-ai-agents Your agent isn't deterministic. Your tests need to be anyway. Gostly records real upstream traffic once and replays it byte-for-byte so the only variable in your agent run is your agent code — same response every test run. ### Record and replay HTTP traffic URL: https://gostly.ai/record-and-replay-http VCR, Betamax, and Polly.js record HTTP calls inside one test runner in one language. Gostly does it at the proxy layer — language-agnostic, structurally redacted, stateful, multi-service. ### Contact URL: https://gostly.ai/contact Contact information for sales, support, and security review. ### Register URL: https://gostly.ai/register Create a Gostly account. Free, Pro, and Team tiers; SSO (SAML, OIDC), 4-role RBAC, and audit log on Team. ### Privacy policy URL: https://gostly.ai/privacy Gostly's privacy policy. ### Terms of service URL: https://gostly.ai/terms Gostly's terms of service. ### Telemetry URL: https://gostly.ai/telemetry Schema of the opt-out-able usage telemetry the agent emits, and the single environment variable that disables it. Bodies and raw identifiers are never transmitted. ## Docs ### Docs URL: https://gostly.ai/docs Gostly product documentation index. ### Quickstart URL: https://gostly.ai/docs/quickstart Quickstart guide. Authenticate with the image registry from the dashboard. Download the generated docker-compose.yml (free tier includes the proxy only; Pro/Team include the control-plane API, dashboard, and inference engine). Set GOSTLY_LICENSE_KEY and BACKEND_URL — the latter can be any reachable HTTP endpoint (localhost, staging, third-party). Pin a specific release image tag rather than :latest for anything beyond a quick trial, so a registry push can't change the stack under a pinned mock library or CI run. Run docker compose up -d. The proxy starts in LEARN mode and listens on port 8080; point your application at http://localhost:8080 instead of your upstream. Every request is forwarded and recorded. If your app speaks HTTPS, set ENABLE_TLS_INTERCEPTION=true and point the client at HTTPS_PROXY=http://localhost:8443; fetch and trust the embedded CA once with 'curl http://localhost:8080/ca.crt > gostly-ca.crt'. Plain ws:// is captured; wss:// interception is not yet supported. Exercise the app or run your test suite. The recorded library grows automatically. Flip to MOCK mode from the dashboard at http://localhost:3000 or via the control-plane API. The shipped compose runs the control plane fail-closed, so control-plane calls on port 8000 carry the X-API-Key header (the value of GHOST_API_KEY from your .env): 'curl -X POST "http://localhost:8000/v1/mode?mode=MOCK" -H "X-API-Key: $GHOST_API_KEY"'. The app keeps talking to localhost:8080; responses are now served from the recorded library, instant and deterministic, with no upstream connectivity required. System requirements: ~6 GB free RAM for the AI inference container (8 GB recommended). Set ENABLE_GENERATION=false in .env to run without inference on smaller machines (~1 GB total). Sharing mocks across environments: ./data/mocks/ contains verbatim HTTP response bodies. If the upstream returns user data, those values are in the files. Add ./data/traffic/ and ./data/license_cache.json to .gitignore by default; commit ./data/mocks/ only after deliberately reviewing it. ### How it works URL: https://gostly.ai/docs/how-it-works The LEARN to MOCK pipeline. In LEARN mode, every proxied request is forwarded to the upstream and the response is recorded in a per-service JSONL file under ./data/traffic/. A normalization pass extracts the structural fields (method, path template, query keys, header set, body shape) and writes a mock row to ./data/mocks/{service}.jsonl. The match cascade is layered. Exact match first: byte-identical request matches its prior response. Session verbatim: a request seen during the active LEARN session is replayed byte-for-byte from an in-memory buffer (bodies and headers, tagged X-Ghost-Mock: session-verbatim) — RAM-only, never leaves the box, and resets on restart or a new LEARN window. Statechart / resource transition: a Harel statechart models resource lifecycles, so POST /charges then GET /charges/{id} returns the created resource instead of a 404 (transitions tagged X-Ghost-Transition). Smart swap: structural fields (timestamps, IDs, tokens) that vary across captures are swapped into the matching response. AI inference at the edge (Pro/Team only, last resort): for requests with no recorded, session, statechart, or structural match, the inference engine generates a response consistent with the schema observed in nearby captures. AI is not on the hot path. For Free tier the cascade stops at smart swap; deterministic strategies cover the matched portion of the traffic, and unmatched requests fall through to PASSTHROUGH or return a structured error. Regulated and latency-sensitive buyers can disable inference entirely and run a fully deterministic stack. ### Proxy setup URL: https://gostly.ai/docs/proxy-setup Proxy setup. The agent is a single Rust binary that terminates HTTP on port 8080 and forwards to BACKEND_URL when in LEARN or PASSTHROUGH mode. Multiple upstreams are supported via per-service configuration: each service has its own match library, mode, and (optionally) its own upstream URL. The agent speaks HTTP on port 8080 by default. It can also terminate TLS itself when ENABLE_TLS_INTERCEPTION is set: a CONNECT forward proxy on port 8443 mints per-host certificates from an embedded CA, and clients trust it by fetching the CA from /ca.crt (or by pointing HTTPS_PROXY at the agent). Fronting the agent with Caddy for TLS termination remains an option. HTTPS-only upstreams are reached over outbound HTTPS regardless of the inbound listener. CI integration: in CI, mount the committed ./data/mocks/ directory and start the proxy in MOCK mode. The proxy runs standalone; the control-plane API and dashboard are not required to serve mocks. Chaos injection: per-service configuration can inject latency, error responses, or partial failures into the served responses to verify the application handles upstream degradation. ### Configuration URL: https://gostly.ai/docs/configuration Configuration reference. Environment variables for the agent, the control-plane API, the inference server, and the platform. GOSTLY_LICENSE_KEY gates the licensed feature set. BACKEND_URL is the upstream for the default service. INITIAL_MODE forces a starting mode independent of the persisted state in ./data/mode.txt. ENABLE_GENERATION and ENABLE_RAG opt the inference server into generation and retrieval respectively; off by default in source, on in the customer-shipped compose. ENVIRONMENT=production triggers fail-fast checks on critical secrets. ### API Reference URL: https://gostly.ai/docs/api Complete control-plane HTTP API reference — authentication, idempotency, error envelope, pagination, rate limits, and every endpoint grouped by feature surface. ## Blog ### Blog URL: https://gostly.ai/blog Gostly engineering and product blog index. ### How Gostly handles security URL: https://gostly.ai/blog/security A proxy that records API traffic sees credentials, tokens, and potentially sensitive response data. Gostly treats that as an architectural constraint, not a policy promise. Credential headers are scrubbed by default on every sink that touches disk or leaves the box. A hard-coded floor of 16 authentication and session headers — Authorization, Cookie, every X-Api-Key, X-Auth-Token, X-Amz-Security-Token variant — is redacted to [REDACTED] on the on-disk JSONL and on everything that ships. The in-memory active-session store keeps them verbatim for byte-exact replay but never leaves the box; MOCK_PERSIST_VERBATIM is an explicit air-gap opt-out for the disk sink. Operator-configured headers can only expand the floor; they cannot shrink it. Bodies are scrubbed structurally. 19 regex categories catch token formats, payment cards, government IDs, contact information, crypto wallet addresses, and IBANs. A 22-element sensitive-key allowlist redacts values by JSON key name regardless of content (password, secret, api_key, refresh_token, cvv, mfa_code). Mock rows carry a scrubbed_at seal; the sync layer refuses to overwrite a scrubbed row with an unscrubbed one. Tenant isolation runs in Postgres Row-Level Security. Every tenant-scoped table has RLS enabled with a tenant_isolation policy gating on a per-request GUC. The API binds the GUC on every request through a typed dependency. Application WHERE clauses are still the primary control; RLS is the database-level second layer that catches application bugs. SSRF protection on webhook replay refuses targets that resolve to loopback, RFC1918, link-local, cloud instance-metadata (169.254.169.254), and eight blocked service ports. Constant-time comparison on every secret — license tokens, API keys, webhook capture tokens — so wrong-but-close credentials don't leak timing. License validation: agents verify the license JWT on a 5-minute refresh cycle with a 4-hour offline grace. A regional outage on Gostly's side does not silently downgrade a customer's stack; degradation after grace is explicit and logged. ### Why choose Gostly URL: https://gostly.ai/blog/why-choose-gostly Most API mocking tools start from a hand-written contract: a Swagger file, an OpenAPI spec, a programmatic mock definition. Gostly starts from the opposite end: real traffic, captured at the proxy layer, structurally indexed and replayed. The wedge is the deterministic contract. The recorded library is the contract; whatever the upstream actually returned is what the mock library serves back. Drift is detected against real behavior, not against a hand-curated spec that may already be stale. The match cascade prefers deterministic strategies first — exact match, structural smart swap — and reaches for AI inference only at the edge of the recorded library. Buyers in regulated or latency-sensitive verticals can disable inference entirely and run a fully deterministic stack. ### Deterministic results in Agentic Workflows URL: https://gostly.ai/blog/deterministic-results-in-agentic-workflows Why an LLM in the replay path is a coin flip, and how a deterministic substrate makes agent tests reproducible by construction. The three patterns we use, and what we don't. ## Compare ### Gostly vs Hoverfly URL: https://gostly.ai/compare/hoverfly Hoverfly is the closest conceptual cousin: an HTTP proxy that captures and replays. Differences are in the match strategy (Gostly's structural smart-swap plus optional AI-at-the-edge cascade) and the security model (structural redaction, Row-Level Security, SSRF protection). Both are self-hosted. ### Gostly vs Microcks URL: https://gostly.ai/compare/microcks Microcks is contract-centric: import a Swagger or AsyncAPI spec, generate stubs from it. Gostly is traffic-centric: capture from upstream, replay. Microcks fits well when the contract is the source of truth; Gostly fits well when the upstream's actual behavior is the source of truth and the contract is incomplete or drifting. ### Gostly vs Mockoon URL: https://gostly.ai/compare/mockoon Mockoon is a desktop mock-server with a GUI. Gostly runs as a Docker stack alongside your app and learns from real traffic; there is no GUI authoring step. ### Gostly vs Optic URL: https://gostly.ai/compare/optic Optic documents API drift by observing traffic. Gostly serves replay traffic to a running application. Different purposes; complementary tools. ### Gostly vs Postman URL: https://gostly.ai/compare/postman Postman Mock Servers are cloud-hosted, hand-authored stubs. Gostly is a self-hosted replay proxy with no manual authoring. ### Gostly vs Prism URL: https://gostly.ai/compare/prism Prism mocks your OpenAPI spec. Gostly records your real upstream and replays it byte-for-byte. Polymorphism, drift, and stateful flows where Prism falls short. ### Gostly vs WireMock URL: https://gostly.ai/compare/wiremock WireMock is the standard hand-written stub-server in the Java ecosystem. Stubs are authored manually as JSON or Java DSL mappings. Gostly is contract-light: stubs are derived from real captured traffic, structurally indexed by request shape, and served back with smart-swap of variable fields. Authoring is automatic. WireMock is well-suited to documenting an expected contract; Gostly is well-suited to reproducing actual upstream behavior, including the parts that aren't in the spec. ### Gostly vs Microsoft AGT URL: https://gostly.ai/compare/microsoft-agt How Gostly differs from Microsoft Agent Governance Toolkit: AGT enforces policy at the agent boundary; Gostly proves behavior matches contract via deterministic upstream replay and signed audit trail. ### Gostly vs AWS AgentCore URL: https://gostly.ai/compare/aws-agentcore How Gostly differs from AWS AgentCore Policy: Gostly is transport-agnostic and multi-cloud, with byte-equivalent upstream simulation rather than Bedrock-bundled policy gating. ### Gostly vs Datadog LLM Experiments URL: https://gostly.ai/compare/datadog-llm-experiments How Gostly differs from Datadog LLM Experiments: deterministic pre-deploy regression signal at the agent-to-API boundary, complementary to Datadog's post-deploy observability.