TapPass Gateway + TapPass Chat — Concept

Status: Concept / positioning draft. Not yet a feature spec. Date: 2026-04-24 (updated 2026-04-28 — sandbox layers, frontend hardening, CLI integration tiers) Origin: Brainstorm about forking LibreChat to release a governed chat product for retail/SMB customers. Expanded during the conversation into a broader reframe of what TapPass is.

1. The thesis

TapPass should reframe itself around a single primitive — a governed LLM gateway — and expose it as three things at once:

An addressable HTTPS endpoint (api.tappass.ai/v1) that speaks OpenAI-compatible and Anthropic-native wire formats. This already exists as tappass/gateway/ — most of the "build the gateway" framing in earlier drafts overstated the work.
A branded end-user chat app (TapPass Chat, a LibreChat fork) that consumes it.
The same existing SDK, dashboard, agents, and pipelines — now explicitly framed as consumers of the same gateway primitive.

The positioning becomes:

TapPass is the governed AI control plane — one endpoint, every model, every tool, every call.

This is not a new product. It is the honest renaming of what TapPass has been all along. The SDK was always a client-side wrapper around the same conceptual thing. Making the primitive addressable directly unlocks a new go-to-market motion (SMB self-serve) without changing the core product.

2. What prompted the reframe

The original ask was narrower: "fork LibreChat, release our own chat gateway automatically governed by TapPass, for retail customers."

Decisions taken during the brainstorm:

#	Question	Decision
Q1	"Retail" meaning	SMB self-serve go-to-market (not retail industry vertical)
Q2	Product shape	Governed chat app — LibreChat is the product, governance is invisible plumbing
Q3	LLM access model	BYOK (users paste their own provider keys), flat per-seat SaaS
Q4	Where TapPass intercepts	TapPass is an OpenAI-compatible proxy; LibreChat points its custom endpoint at it
Q5	Tenancy	Shared tenant for admin (org), separate auth for end users (LibreChat native)
Q6	Fork strategy	Soft fork with minimal overlay (config + env + tiny UI patchset); network egress policy enforces the actual governance boundary

Two follow-up discoveries reshaped the scope:

"Users are seeing Claude Code, Claude Cowork etc., how will we govern that?" — exposed that a chat app alone covers roughly 20% of the SMB AI governance surface. Pushed to the gateway reframe in §1.
The TapPass codebase already has a fully built gateway/ module (OpenAI + Anthropic + MCP + tool execution + capability tokens + LiteLLM-backed multi-provider) and a sandbox/ module (OpenShell with L7 network, Landlock, credential hiding, trust tiers). The work is integration and exposure, not greenfield construction.

3. Governance surface — what actually leaks in 2026

A chat UI is not where the majority of risk lives at a modern SMB. The realistic distribution:

Agentic IDEs — Claude Code, Cursor, Cline, Windsurf. Direct API calls from developer machines with personal keys, with filesystem and repo access.
Agent desktops / wrappers — Claude Cowork, ChatGPT desktop, etc. Local tool execution, MCP-connected.
Scripts & notebooks — raw SDK calls, often with secrets pasted into context.
Browser chat — the visible tip of the iceberg. LibreChat-shaped surface.
Production agents & pipelines — already addressed by the existing SDK integration path.

All of the above hit provider APIs directly. Unless TapPass is on the request path, it sees nothing.

4. Architecture

                                  ┌────────────────────────────────────┐
     ┌─────────────┐              │  Cloud Run sandbox: chat.tappass.ai│
     │  End user   │  HTTPS       │  ┌──────────────────────────────┐  │
     │ (SMB empl.) │─────────────▶│  │ LibreChat fork (Node SPA+BE) │  │
     └─────────────┘              │  │ - HARDENED:                  │  │
                                  │  │   · code interpreter OFF     │  │
                                  │  │   · agents/MCP/plugins OFF   │  │
                                  │  │   · ephemeral FS, no state   │  │
                                  │  │ - APP_TITLE=TapPass Chat     │  │
                                  │  │ - Google OAuth only          │  │
                                  │  │ - Single custom endpoint     │  │
                                  │  │   baseURL=api.tappass.ai/v1  │  │
                                  │  └──────────────────────────────┘  │
                                  │   VPC egress: *.tappass.ai only    │
                                  └──────────────┬─────────────────────┘
                                                 │ OpenAI-compat
                                                 ▼
     ┌──────────────────────┐     ┌────────────────────────────────────┐
     │ Tier 0: env-var       │     │  Cloud Run: api.tappass.ai         │
     │   ANTHROPIC_BASE_URL │ ──▶ │  ┌──────────────────────────────┐  │
     │   on dev machine     │     │  │ TapPass Gateway  [BUILT]     │  │
     │                      │     │  │ - /v1/chat/completions (OAI) │  │
     │ Tier 1: tappass exec │     │  │ - /v1/messages (Anthropic)   │  │
     │   wraps Claude Code  │ ──▶ │  │ - /v1/tools/execute          │  │
     │   in kernel ring     │     │  │ - /v1/tokens/verify  + JWKS  │  │
     │                      │     │  │ - 32-step pipeline           │  │
     │ Tier 2: MCP broker   │     │  │ - Capability tokens (ES256)  │  │
     │   for tool calls     │ ──▶ │  │ - LiteLLM (100+ providers)   │  │
     └──────────────────────┘     │  │ - Circuit breaker, streaming │  │
                                  │  └──────────────────────────────┘  │
                                  └──────────────┬─────────────────────┘
                                                 │ provider-native calls
                                                 │ via org's BYOK keys
                                                 ▼
                               ┌────────┐ ┌─────────┐ ┌────────┐
                               │ OpenAI │ │Anthropic│ │  ...   │
                               └────────┘ └─────────┘ └────────┘

     ┌─────────────┐              ┌────────────────────────────────────┐
     │  Org admin  │─────────────▶│ app.tappass.ai (existing dashboard)│
     │ (signs up,  │              │ - Org/seat mgmt, billing, vault,   │
     │  invites)   │              │   audit trail, policy config       │
     └─────────────┘              │ - New: dev-tools tokens, setup     │
                                  │   snippets, chat seat mgmt         │
                                  └────────────────────────────────────┘

Three surfaces

chat.tappass.ai — end users (LibreChat UI)
api.tappass.ai/v1 — gateway endpoint for everything that speaks HTTP (LibreChat, Claude Code, Cursor, notebooks, SDK, future products)
app.tappass.ai — admin dashboard (existing; gains a "Chat" + "Dev tools" section)

Wire formats already supported by `tappass/gateway/`

Endpoint	Format	Compatible clients
`POST /v1/chat/completions`	OpenAI	OpenAI SDK, LibreChat, LangChain, CrewAI, LlamaIndex, Cursor, VS Code Copilot, curl
`POST /v1/messages`	Anthropic	Claude Code, Cline, Anthropic SDK, Cursor (Anthropic mode)
`POST /v1/tools/execute`	Tool exec	TapPass SDK `govern()` wrapper
`POST /v1/tokens/verify` + `GET /.well-known/jwks.json`	Capability tokens	Tool providers verifying tokens offline
MCP server (governance hooks)	MCP	Claude Code, agent wrappers, any MCP-aware tool

One policy engine. One audit log. One vault. Multiple wire formats — all built.

5. Where each enforcement position runs

The TapPass enforcement plane has five positions per ADR 0001: three rings (in-process) plus two cross-cutting layers (between processes). For this concept, the LibreChat fork adds one more isolation surface (the chat container itself). Understanding the full stack matters for both deployment and the CLI story.

Position	Where it runs	What it isolates	Status
LLM Gateway (cross-cutting, 32-step pipeline)	`api.tappass.ai`, server-side	Prompt / response content — PII, secrets, exfil patterns, policy violations, no-train flags	Built (`tappass/gateway/`, `tappass/pipeline/`)
MCP Broker (cross-cutting)	`api.tappass.ai`, server-side	Tool calls — schema ACL, capability tokens, loop guard, rate limits	Partial (`tappass/gateway/mcp_server.py`; broker mode is new)
Kernel ring (in-process)	Customer dev machine running Claude Code / Cursor / agents	Filesystem (Landlock allowlist), L7 network, exec, credentials. Hot-reloadable (<100ms). Trust-tiered.	Built (`tappass/sandbox/` — OpenShell + nono)
Harness ring (in-process)	Same machine	Tool-call attempts at the agent CLI's permission layer	New — per-CLI providers (claude-code, codex, …)
Interpreter ring (in-process)	Same machine	Code the agent writes (codemode)	New — Monty / V8 isolates / Wasmtime
Cloud Run frontend container (chat-product specific)	`chat.tappass.ai`, the LibreChat fork	The chat process itself — egress lock, ephemeral FS, no code-execution surface	To deploy
End-user browser (chat-product specific)	SMB user's laptop	Standard web app threat model	n/a

The chat fork is the lowest-trust surface (anyone on the internet can hit its login page). Sandbox approach for it is therefore: assume a compromise, contain blast radius. Concrete hardening rules in §10.

Existing sandbox primitives worth knowing

tappass/sandbox/ already provides:

Trust tiers — observer → worker → standard → full. Permissions widen with proven good behavior.
Forbidden zones — 74 protected paths (~/.ssh, ~/.aws, /etc/passwd, browser stores, crypto wallets, financial files).
Exfil blocklist — 60+ paste services, webhooks, cloud-storage exfil destinations.
Credential hiding — agent processes never see real API keys; OpenShell's inference.local proxy injects them at egress.
Browser monitor + credential monitor — background daemons watching for unauthorized access.
Hot-reload via policy_push.py — CISO can tighten an agent mid-session without restarting it.

These are all reusable for the CLI integration in §11 — we're not designing a sandbox, we're wiring the chat product and the dev-tools wrapper into the one TapPass already has.

6. The SMB user's day (what this feels like)

Developer machine: org admin distributes a one-liner that sets ANTHROPIC_BASE_URL=https://api.tappass.ai/v1 and drops a per-user TapPass token. Claude Code, Cursor, Cline — silently governed. (Tier 0 — see §11.)
Browser chat: user opens chat.tappass.ai, signs in with Google, chats.
Random script / notebook: point the OpenAI or Anthropic SDK's base_url at TapPass.
Admin: one audit log at app.tappass.ai shows Claude Code tool calls, chat messages, and notebook traffic — one pane of glass.

7. How existing TapPass pieces map to the reframe

Today	After the reframe
`tappass/gateway/` (built)	The primitive. OpenAI + Anthropic + MCP + tool execution + capability tokens + LiteLLM 100+ providers + circuit breaker + streaming.
`tappass/sandbox/` (built)	Process-level isolation for any AI tool the customer runs locally — reused by Tier 1 of the CLI integration (§11), implementing the kernel ring.
SDK (runtime governance)	One of several integration paths to the gateway. Best when rich metadata / agent-loop / pipeline context matters. Scope unchanged per `feedback_sdk_scope.md`.
Dashboard	Unchanged in purpose. Gains consumers: chat seats, dev-tool tokens, setup snippets.
BYOK vault (`vault_llm_keys`)	The gateway's key-resolution layer on every proxied call.
Agents / Pipelines / Copilot / Playground	Internal consumers of the same gateway. No special-case code paths.
OEM refactor	White-labels ship as a branded gateway + branded chat + branded dashboard — same trinity.
License server (airgapped)	Ships the gateway locally for on-prem customers; same API surface, offline.
`assess/` (pre-sale scanner)	Funnel entry unchanged; report ends with "point your Claude Code / agents here" instead of "integrate our SDK".
`tappass-examples/`	Adds per-tool setup snippets (Claude Code, Cursor, OpenAI SDK base_url swap).

8. Commercial shape

Three integration tiers on one product: (1) point-a-URL gateway, (2) drop-in SDK, (3) deep platform (agents/pipelines). Customers self-select depth.
Two go-to-market motions sharing infra: enterprise high-touch (all three tiers) and SMB self-serve (tier 1 + TapPass Chat). Differ in packaging, sales motion, and pricing.
PLG loop TapPass has not had before: SMB dev pastes ANTHROPIC_BASE_URL=... → TapPass sees tool calls → dashboard surfaces "you have 3 agents and 12 MCP tools running — want to govern them at pipeline level?" → upsell into full platform.
Sharper positioning vs. adjacent categories:
- vs. LiteLLM / Portkey — they route, TapPass governs (policy + audit + compliance)
- vs. CASB (Netskope, Zscaler) — they inspect traffic, TapPass has first-class AI semantics
- vs. ChatGPT Enterprise / Claude Enterprise — those govern their own models, TapPass governs across all providers and all tools

9. TapPass Chat's role in the reframe

Demoted from "the product" to "the visible face." It exists because:

Non-technical SMB users need a chat to send their boss ("use this instead of ChatGPT").
It is the most legible demo — governance is visible in seconds.
It anchors per-seat pricing for SMB procurement.

The center of the story is the gateway + dev-tools governance. Chat is the wedge that makes it buyable without a technical conversation.

10. LibreChat fork approach + frontend hardening

Soft fork with minimal overlay — "B-minimal":

Config layer — LibreChat's librechat.yaml + env vars handle branding text (APP_TITLE, CUSTOM_FOOTER), OAuth (GOOGLE_CLIENT_ID), feature toggles (interface.*), and custom-endpoint definition.
Network layer — Cloud Run VPC egress policy restricts the container to *.tappass.ai + Google OAuth endpoints only. This is the actual security boundary. A user who configures a rogue endpoint in the UI still fails at the network.
Thin UI overlay — small patchset hides: API-key entry fields, "add endpoint" UI, endpoint dropdown. Mounted volume swaps logo/favicon.

Upstream sync cadence: weekly git rebase upstream/main with a deliberately tiny patch set. Re-check on each sync whether upstream added a new "bring your own endpoint" flow needing suppression.

Verified gaps in LibreChat config (informs the overlay)

Config-only is not sufficient because:

No way to prevent users from adding their own endpoints in the UI (deal-breaker for governance without the network backstop).
No way to hide the API-key entry field in settings.
No logo / favicon / theme-color env vars (baked-in assets).
No way to hide the endpoint dropdown (only modelSelect).

The network egress policy + tiny UI overlay close these gaps.

Frontend hardening checklist

LibreChat should be the dumbest possible frontend. Every dangerous capability is delegated to a TapPass service that's already governed and sandboxed.

VPC egress lock to *.tappass.ai + Google OAuth endpoints only.
Disable LibreChat's code interpreter entirely. Don't inherit a remote-code-execution surface. If a user wants code execution, route them to a TapPass agent which already runs in OpenShell with proper isolation.
Disable LibreChat's agents / MCP / plugins inside the chat fork. Point users to TapPass's MCP server (gateway/mcp_server.py) which is already governed. Two MCP entry points = double governance work; don't.
No third-party plugin marketplace. LibreChat's plugins feature is a known supply-chain hazard — disabled by config.
Move stateful storage to TapPass-managed DB. Replace LibreChat's default Mongo with the existing TapPass session/audit tables. Chat container becomes stateless — a compromise loses only in-flight session state.
Ephemeral container filesystem. No persistent user data inside the chat container.
File uploads off in v1. If turned on later, files flow to a TapPass-managed bucket and pass through the gateway pipeline (PII / exfil / malware) before being readable by an LLM call.
Unprivileged container user, read-only root filesystem, no Docker socket mount.
No outbound DNS to provider domains — even if user pastes a fake config, requests can't reach api.openai.com directly.

The fork ends up being closer to a styled chat client over the gateway than "LibreChat with branding."

11. CLI integration & three sandbox tiers

Three integration tiers, customer self-selects depth. Each tier maps to enforcement positions per ADR 0001. All three already have backing in the existing tappass/gateway/ and tappass/sandbox/ modules.

Tier 0 — Zero-effort (LLM Gateway only)

Customer admin distributes:

export ANTHROPIC_BASE_URL=https://api.tappass.ai/v1
export ANTHROPIC_API_KEY=<tappass-issued-token>

Claude Code already respects ANTHROPIC_BASE_URL. Every Claude Code message hits the TapPass LLM Gateway, runs the 32-step pipeline, audit log captures everything. No install, no in-process rings, no tool-level broker.

This is the SMB-friendly default — the dev pastes two lines and is governed. Same shape works for Cursor, Cline, the OpenAI SDK (with base_url), curl scripts.

What it covers: prompt-level PII / secret scrub, response filtering, audit, quotas, no-train enforcement, BYOK key resolution.

What it misses: tool-call exfiltration at runtime (Claude Code running a shell command that reads ~/.ssh or curls an exfil endpoint).

Tier 1 — Wrapped invocation (+ Kernel ring)

TapPass ships a thin CLI wrapper:

tappass exec -- claude code "fix the auth bug"

The wrapper:

Resolves a per-session capability token from TapPass (org_id + agent_id + scope).
Sets ANTHROPIC_BASE_URL and the token in the child env.
Launches Claude Code inside a kernel-ring sandbox derived from OPA policy. The kernel-ring provider (OpenShell on servers, nono on developer laptops, sandbox-exec on macOS) enforces:
- Filesystem allowlist scoped to the current repo (Landlock allow_read / allow_write).
- L7 network allowlist: api.tappass.ai, github.com, package registries — nothing else.
- Credential hiding via inference.local so even shell commands Claude Code runs can't see real keys.
- Trust tier auto-selected from tappass/sandbox/trust_tiers.py based on the user / repo / behavior history.
Streams structured audit events to TapPass during the session.
Hot-reloads Compiled Policy if the CISO tightens permissions mid-session (policy_push.py).

This catches the case where Claude Code runs a shell tool that exfiltrates ~/.ssh or hits an unauthorized API. Tier 0 alone misses tool-call exfil; this tier doesn't.

Tier 2 — MCP Broker (+ tool-call governance)

Claude Code (and any MCP-aware tool) connects through TapPass's MCP Broker (tappass/gateway/mcp_server.py). Every MCP tool invocation is policy-checked, capability-token-bound, and audited at the tool boundary — separate from LLM-call governance. Tools that need privileged data (vault secrets, internal APIs, customer DB) go through here. The customer's own internal MCP servers can be wrapped behind the TapPass Broker for the same effect.

How the tiers compose against the enforcement positions

Tier	Adds	Enforcement positions used
Tier 0	LLM Gateway	LLM Gateway only
Tier 1	+ Kernel ring (process containment)	LLM Gateway + Kernel ring (+ Harness ring via the wrapper)
Tier 2	+ MCP Broker (tool RPC governance)	LLM Gateway + rings + MCP Broker

A fully governed Claude Code session at a serious customer uses all three tiers (and adds the Interpreter ring when codemode is in use). An SMB on day one uses just Tier 0. The progression maps to the commercial tiers in §8.

Pitch to a dev-heavy SMB

"Tier 0 today — paste two env vars, every Claude Code message governed and audited via the LLM Gateway. Tier 1 next week when the wrapper ships — Claude Code runs in a kernel-ring sandbox so even tool calls can't leak data. Tier 2 when you want the deepest control — every tool invocation policy-checked at the MCP Broker."

12. Open decisions not yet resolved

Captured for the feature doc to address:

Default governance policies shipped out of the box for SMB chat (PII / secret scrubbing rules, no-train enforcement per provider, default quotas, response filtering).
MVP LibreChat feature set — confirm hardening checklist (§10) lines up with what we ship; decide on RAG, image gen, web search, speech (lean: all OFF in v1).
Billing mechanics — Stripe tiers, seat pricing, free-trial shape, dev-tools-token pricing (per seat vs. separate vs. metered).
Scope for v1 — Tier 0 ships at launch alongside chat (lean: yes — gateway already supports it, leaving it out creates an obvious demo hole). Tier 1 wrapper CLI (kernel ring): v1.1. Tier 2 MCP Broker integration: v1.1 or v1.2 depending on customer pull.
Positioning assets — marketing page, docs structure, naming ("TapPass Gateway" as explicit product? or just "TapPass"?).
Sales motion split — who sells what, how the upsell from SMB gateway-only to enterprise platform happens operationally.
Where this concept lives long-term — working-assets GitHub repo vs. internal dashboard vs. product wiki.

13. Strategic questions worth pressure-testing later

Not blocking, but worth revisiting before the feature doc:

Does reframing TapPass around "the gateway" confuse existing enterprise pipeline/agent messaging, or sharpen it?
Is "gateway" the right public-facing noun, or does it sound like plumbing to non-technical buyers? Alternatives: "control plane," "safe layer," "governed endpoint."
How does this interact with the OEM/white-label strategy? If white-labels are branded gateways, does TapPass-the-brand still sell retail, or only via OEMs?
Does the PLG loop cannibalize enterprise sales velocity, or feed it?
For Tier 1 (kernel-ring wrapper), do we ship an installer (Homebrew, MSI, .deb) or a one-line curl? Distribution surface is non-trivial.
For Tier 2 (MCP Broker), how do we handle customer-internal MCP servers — proxy them, federate, or require they re-register tools through TapPass?

TapPass Gateway + TapPass Chat — Concept

TapPass Gateway + TapPass Chat — Concept

1. The thesis

2. What prompted the reframe

3. Governance surface — what actually leaks in 2026

4. Architecture

Three surfaces

Wire formats already supported by tappass/gateway/

5. Where each enforcement position runs

Existing sandbox primitives worth knowing

6. The SMB user's day (what this feels like)

7. How existing TapPass pieces map to the reframe

8. Commercial shape

9. TapPass Chat's role in the reframe

10. LibreChat fork approach + frontend hardening

Verified gaps in LibreChat config (informs the overlay)

Frontend hardening checklist

11. CLI integration & three sandbox tiers

Tier 0 — Zero-effort (LLM Gateway only)

Tier 1 — Wrapped invocation (+ Kernel ring)

Tier 2 — MCP Broker (+ tool-call governance)

How the tiers compose against the enforcement positions

Pitch to a dev-heavy SMB

12. Open decisions not yet resolved

13. Strategic questions worth pressure-testing later

Wire formats already supported by `tappass/gateway/`