GhostAPI

Local API simulation and test evidence for AI-assisted development.

GhostAPI gives applications and coding agents a local target for selected Stripe, Resend, OpenAI, Twilio, GitHub, Discord, and generic REST workflows. It records heuristically sanitized traffic, injects deterministic failures, exposes MCP controls, and turns captured behavior into repeatable tests.

On supported Linux hosts, ghostapi run can execute a test command inside a loopback-only network namespace. It is not a hostile-code or filesystem sandbox.

Quickstart · Security model · Provider coverage · Release evidence

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.

When a client is configured against a live provider, 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 provides a local endpoint at 127.0.0.1:8080. Requests sent to that endpoint are classified, heuristically sanitized, recorded in bounded local stores, and answered by implemented provider packs or generic fallback behavior. You can inspect the result in the dashboard, control local behavior through MCP, and turn captured failures into repeatable tests.

Verified Locally, Not Customer-Validated Yet

The public repository contains reproducible tests for local provider simulation, Linux namespace enforcement, package installation, and hosted-pilot authorization. GhostAPI does not yet claim production customers, paid pilots, or a deployed team service.

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":"ada@example.com","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

Feature	What it does
Local API simulation	Gives explicitly configured SDKs and applications a local target instead of a live provider.
Provider-shaped behavior	Returns deterministic objects and errors shaped like the implemented subset of each provider API; it does not claim live-provider parity.
Live dashboard	Shows requests and responses, filters traffic by provider, generates tests, and arms scenarios.
MCP control plane	Lets compatible coding agents inspect state, read traffic, configure responses, and toggle Chaos Mode.
Stateful synthetic worlds	Maintains deterministic local identities and state across Stripe, GitHub, email, and REST projections.
Scenarios and record/replay	Saves sanitized sandbox traffic and replays it offline as deterministic fixtures.
Contract drift checks	Imports bounded OpenAPI/HAR contracts and classifies breaking, non-breaking, and uncertain changes.
Agent evals and evidence	Produces bounded reports with a local self-consistency hash, verifiable while the runtime and local storage remain trusted.
Secret-risk reduction	Heuristically masks recognized secret-shaped headers, query parameters, bodies, paths, events, prompts, and cache inputs.
Fault testing	Forces latency, provider errors, card declines, rate limits, and other unhappy paths.
Safety controls	Includes local approvals, scoped budgets, kill switches, circuit breakers, ledgers, and reconciliation for synthetic actions.
Reliability tooling	Tracks local SLO samples, cost attribution, runtime health, backups, inventory, and attack-path metadata.

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	Included behavior
Stripe	Customers, products, prices, subscriptions, invoices, payment intents, payment methods, checkout sessions, refunds, pagination, lifecycle scenarios, and signed local webhooks.
Resend	Deterministic email-shaped requests, responses, validation, and failure behavior.

Provider-shaped adapters and generic inference

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

Unsupported Stripe and Resend pack operations fail diagnostically. Legacy adapters and generic REST inference may return a synthetic fallback response for unrecognized routes; such responses do not indicate provider support or parity.

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@0.2.1", "mcp"]
    }
  }
}

Available tools:

Tool	Purpose
inspect_state	Read current local API objects.
get_traffic_logs	Inspect sanitized recent traffic.
set_api_behavior	Force a deterministic response for a method and path.
toggle_chaos_mode	Enable or disable local latency and failure injection.

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

npx @yiaany/ghostapi setup --write

Connect only trusted local MCP clients. MCP tools can read retained traffic and state and can modify local simulation behavior; MCP is not an authentication or egress boundary. Pin the package version in persistent MCP configuration or use a reviewed local installation.

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

Security Boundaries

GhostAPI uses local-first defaults, explicit external-LLM opt-in, and heuristic secret masking. 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.
• On non-loopback binds, every route except / and /health requires a strong GHOSTAPI_AUTH_TOKEN. The token provides access control, not encryption.
• 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 and incomplete. 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.
• Evidence hashes are local self-consistency checks, not signatures, immutable provenance, or proof against a same-user editor.
• Current run evidence records namespace lifecycle and GhostAPI-local traffic; it does not enumerate kernel-denied socket attempts.

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

Explicit Non-Goals

• No live-provider parity guarantee.
• No complete secret-redaction guarantee.
• No hostile-code filesystem sandbox.
• No equivalent process-egress enforcement on Windows or macOS.
• No deployed hosted service, SLA, compliance certification, or production credential executor.

Platform Support

Platform	Local API and dashboard	ghostapi run enforcement
Linux	Supported on Node.js 20+	Supported when unshare, iproute2, and namespace preflight pass.
Windows	Supported on Node.js 20+	Not implemented; fails closed.
macOS	Supported on Node.js 20+	Not implemented; fails closed.

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 Experiment

No hosted or enterprise service is currently available. The hosted/ directory is an undeployed experimental implementation, excluded from the npm package and unsupported for production use. Its live OAuth, dependency, migration, load, failover, backup, and disaster-recovery behavior has not been proven in staging.

Development

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

Hosted pilot checks:

cd hosted
npm ci
npm run check

See CONTRIBUTING.md, PROVENANCE.md, and docs/releases/ for the contribution and release boundaries.

Documentation

• Usage guide
• MCP setup
• Policy reference
• GitHub Actions integration
• Generic CI integration
• Stripe provider pack
• Security policy
• Threat models
• Project provenance
• Release evidence
• Release readiness
• Migration and rollback

License

MIT. See LICENSE.