GhostAPI

The local internet for AI coding agents.

Build and test third-party API integrations locally, without charging cards, sending messages, leaking production keys, or mutating real services.

Quickstart · Features · Providers · MCP · Safety · Enterprise

npx @yiaany/ghostapi start --open

Why GhostAPI

Coding agents can write a Stripe checkout, an OpenAI workflow, a GitHub automation, or an email integration in minutes. The dangerous part is what happens when they run that code.

Without a safe local target, a test can:

• charge a real card;
• send a real email or SMS;
• create or modify real GitHub resources;
• spend API credits;
• leak credentials into logs, prompts, screenshots, or test fixtures.

GhostAPI gives your application and coding agent a local API world at 127.0.0.1:8080. Requests are detected, sanitized, recorded, and answered with deterministic provider-shaped responses. You can inspect the result in the dashboard, control behavior through MCP, and turn failures into repeatable tests.

Quickstart

Start the local server and dashboard:

npx @yiaany/ghostapi start --open

Send a Stripe-shaped request:

curl -X POST http://127.0.0.1:8080/v1/customers \
  -H "content-type: application/json" \
  -H "authorization: Bearer stripe_test_ghostapi" \
  -d '{"email":"[email protected]","name":"Ada Lovelace"}'

Open the dashboard at http://127.0.0.1:8080/dashboard. The request appears in live traffic with its provider, request body, generated response, source, status, and timing.

Initialize GhostAPI inside an existing repository:

npx @yiaany/ghostapi init
npx @yiaany/ghostapi doctor

init creates local configuration, a versioned safety policy, MCP snippets, and agent instructions without overwriting existing files.

On a supported Linux host, run a command inside the loopback-only network namespace:

npx @yiaany/ghostapi run -- npm test

On Windows and macOS, ghostapi run fails closed because an equivalent process-isolation backend is not implemented. The local API server and dashboard still work normally.

What You Get

Dashboard

The dashboard is the fastest way to understand what an agent or application actually did.

• Watch traffic arrive in real time over SSE.
• Inspect sanitized request and response JSON.
• Filter by Stripe, Twilio, Resend, GitHub, Discord, OpenAI, or generic REST.
• Generate a Vitest test from a captured request.
• Generate and copy setup files for supported coding agents.
• Arm deterministic scenario presets.
• Toggle Chaos Mode and inspect the local safety report.

Dashboard and API routes are token-protected on every non-loopback bind. Use HTTPS or a secure tunnel when exposing GhostAPI beyond localhost.

Provider Support

GhostAPI has two levels of provider support.

Stateful provider packs

Provider-shaped adapters and generic inference

OpenAI, Twilio, GitHub, Discord, and generic REST routes are detected and receive provider-shaped mock responses and errors. These adapters are useful for local development, but they do not claim complete parity with every live-provider endpoint.

Unsupported endpoints fail diagnostically instead of silently pretending that an operation succeeded.

SDK Setup

Stripe:

import Stripe from "stripe";

export const stripe = new Stripe(
  process.env.STRIPE_SECRET_KEY ?? "stripe_test_ghostapi",
  {
    host: process.env.GHOSTAPI_HOST ?? "127.0.0.1",
    port: Number(process.env.GHOSTAPI_PORT ?? "8080"),
    protocol: process.env.GHOSTAPI_PROTOCOL ?? "http"
  }
);

OpenAI:

import OpenAI from "openai";

export const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY ?? "sk-ghostapi",
  baseURL: process.env.GHOSTAPI_OPENAI_BASE_URL ?? "http://127.0.0.1:8080/v1"
});

Generic REST:

curl -X POST http://127.0.0.1:8080/tasks \
  -H "content-type: application/json" \
  -d '{"title":"Add integration tests","status":"open"}'

MCP For Agents

Start the MCP server:

npx @yiaany/ghostapi mcp

Generic MCP configuration:

{
  "mcpServers": {
    "ghostapi": {
      "command": "npx",
      "args": ["-y", "@yiaany/ghostapi", "mcp"]
    }
  }
}

Available tools:

Generate setup snippets for Cursor, Claude, Cline, Aider, Codex, OpenCode, Gemini CLI, Goose, OpenClaw, Hermes, and generic MCP clients:

npx @yiaany/ghostapi setup --write

Scenarios, Contracts, And Evals

Record approved sandbox traffic into a sanitized offline bundle:

ghostapi record \
  --input capture.har \
  --allow-sandbox-host api.sandbox.example \
  --approve

Replay it without network access:

ghostapi replay bundle.json --requests requests.json

Import and compare API contracts:

ghostapi contract import-openapi --input openapi.json
ghostapi contract diff \
  --baseline base.contract.json \
  --candidate head.contract.json \
  --policy ghostapi.policy.yaml \
  --ci

Generate sanitized CI evidence:

ghostapi evidence generate --policy ghostapi.policy.yaml --ci

Run a deterministic agent eval:

ghostapi eval \
  --template retry-after \
  --evidence .ghostapi/reports/latest.json \
  --ci

Safety Boundaries

GhostAPI is designed to fail closed, but its boundaries are explicit:

• Real provider calls are disabled by default.
• Ambient OPENAI_API_KEY does not enable external generation.
• External LLM generation requires an explicit flag plus a separate GHOSTAPI_LLM_API_KEY.
• Non-loopback access requires a strong dashboard token.
• External response redirects, unsafe response headers, traversal, remote schema references, symlinks, archives, and oversized inputs are rejected where applicable.
• Persistent stores have size, entry, retention, or rotation limits.
• The Linux run backend provides loopback-only process network isolation when namespace preflight succeeds.
• run is not a hostile-code filesystem sandbox.
• Secret masking is heuristic. Use synthetic credentials and data even in local fixtures.
• Local approval, action, credential, ledger, trust, and safety components execute synthetic operations only. They are not a production-provider executor.

Read the detailed threat models in docs/security and the reporting policy in SECURITY.md.

Platform Support

Check the current machine:

ghostapi doctor --json
ghostapi doctor --egress

Health Endpoints

GET /health             process liveness, HTTP 200 while state can be evaluated
GET /health/readiness   structural readiness, HTTP 503 when a required store is unsafe

Hosted And Enterprise

The hosted/ directory contains an implemented but not yet deployed team pilot. It includes:

• organizations, projects, invitations, memberships, and role-based access;
• tenant-safe report and scenario APIs;
• hashed and rotatable CI ingest keys;
• bounded request handling, CSRF checks, security headers, quotas, and abuse limits;
• PostgreSQL migrations, idempotency, outbox dispatch, worker leases, retries, dead letters, and retention cleanup;
• Redis-backed rate limiting, QStash verification, readiness checks, and a non-root Docker image.

It is not advertised as a production SaaS yet. Live OAuth, Redis, QStash, load, failover, backup/restore, and disaster-recovery behavior must still be proven in staging before a paid pilot.

The detailed product plan for a complete enterprise edition is available in docs/enterprise-product-roadmap-ru.md.

Development

npm ci
npm run lint
npm run typecheck
npm test
npm run build
npm run smoke:package

Hosted pilot checks:

cd hosted
npm ci
npm run check

See CONTRIBUTING.md, docs/release-readiness.md, and docs/development/verification-0.1.8.md for the complete verification boundary.

Documentation

• Usage guide
• MCP setup
• Policy reference
• GitHub Actions integration
• Generic CI integration
• Stripe provider pack
• Security policy
• Threat models
• Release readiness
• Migration and rollback
• Enterprise roadmap in Russian

License

MIT. See LICENSE.