llm-cli-gateway / site

# llm-cli-gateway

> Secure local control plane for AI coding agents. Operate Claude Code, Codex CLI, Gemini/Antigravity, Grok Build, Mistral Vibe, Cognition Devin, Cursor Agent, and optional HTTP API providers from supported MCP clients while keeping execution workspace-scoped, approval-gated, durable, and auditable.

## Links

- [Homepage](https://llm-cli-gateway.dev/): Product overview, provider matrix, and deployment positioning.
- [Developer docs](https://llm-cli-gateway.dev/docs): Conventional developer documentation entry point.
- [API reference](https://llm-cli-gateway.dev/api): Conventional API reference for the HTTP MCP transport, scopes, endpoints, and JSON errors.
- [Developer portal](https://llm-cli-gateway.dev/developers): Quickstart and self-serve developer resources.
- [OpenAPI spec](https://llm-cli-gateway.dev/openapi.json): OpenAPI 3.1 description for the HTTP MCP transport.
- [Install guide](https://llm-cli-gateway.dev/install.md): Agent-readable setup instructions for local stdio and remote HTTP gateway use.
- [Full agent guide](https://llm-cli-gateway.dev/agents.md): Long-form agent-facing guide for installation, connection modes, security model, tool families, workflows, and troubleshooting.
- [Tool index](https://llm-cli-gateway.dev/tools.md): Runtime-derived MCP tool list generated from the gateway's actual `tools/list` response.
- [Coding-agent gateway technical guide](https://llm-cli-gateway.dev/guides/coding-agent-gateway-technical-guide.md): Architecture, setup, workflows, comparison, and best practices for using llm-cli-gateway as an MCP control plane.
- [Personal Agent Config Kit guide](https://llm-cli-gateway.dev/guides/personal-agent-config-kit.md): Single-developer Git-synchronised baseline and repository-overlay configuration across workstations.
- [Cross-model review workflow](https://llm-cli-gateway.dev/workflows/cross-model-review.md): Deterministic workflow demo showing implementation, review, polling, and fix loops.
- [Discovery matrix](https://llm-cli-gateway.dev/DISCOVERY.md): Route matrix for machine-readable files, generated aliases, headers, sitemap inclusion, and validation commands.
- [Repository](https://github.com/verivus-oss/llm-cli-gateway): Source code, issues, releases, skills, and operational workflows.
- [npm package](https://www.npmjs.com/package/llm-cli-gateway): Published package for `npx -y llm-cli-gateway`.
- [Agent metadata](https://llm-cli-gateway.dev/.well-known/agent.json): Structured metadata for MCP clients and retrieval agents.
- [Integration declaration](https://llm-cli-gateway.dev/.well-known/integrations.json): Owner-declared MCP surfaces and auth facts for integrations.sh-style discovery.
- [API catalog](https://llm-cli-gateway.dev/.well-known/api-catalog): Machine-readable service catalog with docs and MCP endpoint pointers.
- [AI catalog alias](https://llm-cli-gateway.dev/.well-known/ai-catalog.json): JSON alias generated from the same catalog source as `/.well-known/api-catalog`.
- [MCP server card](https://llm-cli-gateway.dev/.well-known/mcp/server-card.json): MCP server package and remote endpoint metadata.
- [MCP card alias](https://llm-cli-gateway.dev/.well-known/mcp.json): JSON alias generated from `/.well-known/mcp/server-card.json`.
- [XML sitemap](https://llm-cli-gateway.dev/sitemap.xml): Search-engine sitemap for public site resources.
- [Human sitemap](https://llm-cli-gateway.dev/sitemap.md): Markdown index of public resources.

MCP Registry name: `io.github.verivus-oss/llm-cli-gateway`

## When to use

Use llm-cli-gateway when an MCP client needs to operate Claude Code, Codex,
Gemini/Antigravity, Grok Build, Mistral Vibe, Devin, Cursor Agent, or configured
API providers through one local control plane. It is best for cross-model code
review, durable long-running jobs, provider-native session continuity, approval
gating, and remote HTTP MCP access scoped to registered workspaces.

Do not use it as a hosted model API replacement. Provider CLIs and configured
API providers keep their own credentials, tools, limits, and billing.

## Use cases

- Capture a complete hashed Git change with `review_changes`, or run
  implementation in one provider and review with two or more other models.
- Start `*_request_async` jobs and recover results after disconnects or restarts.
- Reuse provider-native sessions without losing local CLI semantics.
- Expose a local MCP server to remote clients with bearer or OAuth authentication.
- Register workspace aliases so remote calls cannot access arbitrary host paths.
- Keep one developer's verified instruction baseline and repository overlays in
  sync across workstations with Personal Agent Config Kit.

## Launch

```bash
npx -y llm-cli-gateway                 # local, stdio (default)
llm-cli-gateway --transport=http        # remote, HTTP (opt-in)
```

Transports: stdio (default, local) and HTTP (remote). HTTP binds 127.0.0.1:3333/mcp by default and authenticates with a static bearer token (`LLM_GATEWAY_AUTH_TOKEN`) or the built-in OAuth 2.0 server (PKCE on by default, opt-in consent gate, trusted-principal-header integration for a proxy front door). A shared static bearer token is one shared principal, not multi-tenant isolation.

OAuth scopes documented for HTTP integrations: `mcp`, `workspace:admin`, and
`cli:admin`. Remote workspace creation or registration also requires
`LLM_GATEWAY_WORKSPACE_ADMIN=1`; remote provider-admin operations also require
`LLM_GATEWAY_CLI_ADMIN=1`.

## Core tools

- `claude_request`, `codex_request`, `gemini_request`, `grok_request`, `mistral_request`, `devin_request`, `cursor_request`
- `api_<name>_request` for configured HTTP API providers, with `api_<name>_request_async` when async jobs are enabled
- `*_request_async` for registered CLI providers, `codex_fork_session`
- `llm_job_status`, `llm_job_watch`, `llm_job_result`, `llm_job_cancel`, `llm_request_result`
- For resumable large job output, call `llm_job_result` with `rawOutput:true` and
  continue each stdout/stderr stream from its non-null next offset. Default
  display output is transformed and cannot be resumed from captured-stream offsets.
  Local stdio raw pages concatenate to captured streams; remote raw pages remain
  provider-session-ID-redacted and are not byte-for-byte provider output.
- `session_create`, `session_list`, `session_set_active`, `session_get`, `session_delete`, `session_clear_all`
- `workspace_create`, `workspace_list`, `workspace_get`, `workspace_register_existing_repo` (remote calls require a registered workspace)
- `review_changes`, `validate_with_models`, `second_opinion`, `compare_answers`, `red_team_review`, `consensus_check`, `ask_model`, `synthesize_validation`, `list_available_models`, `job_status`/`job_result` (validation jobs); `review_changes` and `validation_receipt` require a durable validation-run store (`sqlite` or `postgres`)
- `list_models`, `provider_tool_capabilities`, `cli_versions`, `cli_upgrade`, `upstream_contracts`, `provider_subcommands_*`, `approval_list`, `llm_process_health`
- Local-only Personal Agent Config Kit: `config_init`, `config_publish`,
  `config_sync`, `config_status`, `config_rollback`, `config_ack_stale`,
  `config_recover_kit_attempt`, and `explain_effective_config`

For the generated full tool list, read [tools.md](https://llm-cli-gateway.dev/tools.md).

## Positioning

llm-cli-gateway wraps installed provider CLIs and can register configured HTTP API providers. Provider CLIs keep their native credentials, local file access, tool execution, and session semantics. API-provider keys are read from named environment variables at request time and are not written to config, diagnostics, persisted payloads, dedup keys, logs, or the flight recorder. The gateway adds MCP access, async orchestration, durable job state, validation workflows, approval surfaces, and a single control point for supported local and remote clients.

Unscoped local CLI children run in fresh private temporary directories, not the
gateway repository. Cwd-scoped latest-session continuation needs an explicit or
configured workspace target. Codex new and resume prompts use stdin.
`codex_fork_session` remains argv-bound and rejects oversized UTF-8 prompts as
non-retryable `input_too_large`. Every caller-controlled argv value is checked
in its final encoded form before spawn. The resolved command line also has a
conservative platform-specific aggregate byte budget and a 2,048-element cap;
Windows preflight assumes the smaller npm .cmd/.bat wrapper limit until command
resolution proves a native executable. Handler-added native session flags are
admitted before workspace, session, provider-artifact handoff, or durable-job
side effects on non-Kit requests. Claude Kit projects its eventual argv before
compiled-context artifact materialization or durable Kit-session allocation.
Native `E2BIG` remains a redacted fallback. Inputs are never silently truncated.
An embedded NUL byte in command or argv is rejected before spawn as
non-retryable `invalid_input`. Public results, long-lived job memory, durable
args, and async flight rows use a fixed invalid-argv marker, while the optional
duplicate durable payload is suppressed. Public and retained fields omit the
rejected vector and Node's value-echoing native message. Stdin-backed requests require a successful complete-payload
callback before a clean child exit can complete; closed or pending delivery
becomes a fixed non-sensitive failure.

It runs local-first over stdio, and remotely over HTTP behind real authentication: a static bearer token, a built-in OAuth 2.0 server, or a trusted-principal-header integration for an identity proxy you already run. Every session, job, and stored request is owned by a principal and access is enforced per principal. OAuth and trusted-principal callers cannot cross that boundary; callers sharing one static bearer token deliberately share one principal. Remote provider calls require a registered workspace, and a dangerous OAuth configuration fails closed. The 2.9.0 release remediated all 17 findings of a multi-LLM red-team of the external and internal MCP surface before the remote path was documented as ready.

## Optional

- [Maintainer operations](https://llm-cli-gateway.dev/maintainers.md): Public notes on release credentials, Cloudflare Pages deploys, search indexing, and token smoke workflows.