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

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.

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.

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.

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.

GhostAPI has two levels of provider support.

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.

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"}'

Start the MCP server:

npx @yiaany/ghostapi mcp

Generic MCP configuration:

{
  "mcpServers": {
    "ghostapi": {
      "command": "npx",
      "args": ["-y", "@yiaany/ghostapi@0.2.0", "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

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.

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

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.

• 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.

Check the current machine:

ghostapi doctor --json
ghostapi doctor --egress

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

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.

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.

• 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

MIT. See LICENSE.