Switchyard

Shared provider runtime for AI apps.

Switchyard turns end-user BYOK + Web/Login access into one service-first
runtime that AI products can call without rebuilding provider routing,
credential/session handling, and diagnostics from scratch.

It is not a chat product, not a personal assistant, and not another
all-in-one AI platform. It exists to be the shared runtime layer that other AI
apps can depend on.

Switchyard storefront loop preview.

Builder Thesis

One shared provider runtime for AI apps.

Use Switchyard when you want AI products to plug into real end-user access
lanes without every product re-inventing provider contracts, session logic,
and diagnostics.

Current Public Boundary

Today the truthful public story is:

Primary public front door: the GitHub Pages docs atlas plus this root
README
Primary repo-native runtime surface: apps/service/ and the
service/runtime HTTP contract
Secondary machine-readable surface:
packages/surfaces/mcp/server.json, a read-only MCP descriptor
Builder-facing packet:
distribution/claude-marketplace/plugins/switchyard-builder-suite/skills/runtime-diagnostics/
plus starter packs and host examples
Not claimed today: official marketplace listings, official MCP Registry
listing, npm publication, hosted multi-tenant runtime, write-capable MCP, or
full consumer parity

Artifact-ready still does not mean listed-live.

Public Language Policy

Switchyard now treats the public front door as English-first.

The default landing path for global developers stays English-first.
Bilingual support remains available through glossary and i18n helper pages.
Live/browser realism notes belong in proof and runbook surfaces, not in the
stable top-level product sentence.

Open The Right Door

If you need to...	Open this first
understand the product in 30 seconds	docs/media/30-second-overview.md
run the shortest first success	docs/first-success.md
inspect what is really proved today	docs/public-proof-pack.md
see what is package-ready vs listed-live	docs/public-distribution-ledger.md
bootstrap a local workstation or inspect workstation-bound reality	docs/runbooks/dev-bootstrap.md
browse the public docs front row	docs/index.html and docs/README.md

If you are touching Switchyard for the first time, stop there.

The heavier shelves still exist, but they are not first-row front door pages:

support signboard and bootstrap runbook
contracts and blueprints
submission-packet accounting
builder catalog internals
testing/governance reference pages

The old Wave 1 working packs were relocated out of the public docs plane. The
legacy docs/blueprints/wave1/* paths now act only as relocation notes, while
the real working copies live under .agents/internal-docs/wave1/.

30-Second Version

If you only remember four lines, remember these:

Switchyard is not another AI app.
It is a shared provider runtime for AI apps.
It turns BYOK + Web/Login access into a service-first substrate that other
AI products can call.
Today it ships a repo-native runtime, a partial read-only MCP surface, a
runtime-diagnostics packet, starter packs, and truth-first public docs. npm,
registry, marketplace, Docker, and broader publication remain later lanes.

First Success

If you want the fastest truthful first success, run the shortest bounded path:

Start the local runtime:
```
pnpm run start:service-local
```
Prove the read-only truth surface is alive:
```
pnpm run example:mcp-inspector
```
Prove the runtime can accept one minimal invoke:
```
pnpm run example:runtime-bridge
```

The default service port is http://127.0.0.1:4010.

If you want the full step-by-step path and failure routing, open
docs/first-success.md.

Why Switchyard Exists

Many AI products keep rebuilding the same messy layer:

provider contracts
auth/session plumbing
provider routing
diagnostics and remediation
builder starter surfaces

Switchyard exists so that this repeated work can become one reusable runtime:

a shared provider runtime that AI apps can plug into, instead of each app
re-inventing the provider layer alone

What It Is

a shared provider runtime for AI apps
a service-first runtime surface with SDK and MCP companion surfaces
a builder-facing repo that keeps proof, starter packs, and truth contracts
aligned
a runtime layer that stays fail-closed on claims it cannot honestly prove

What It Is Not

not a chat product
not a personal assistant
not a control-plane-first SaaS
not a hosted multi-tenant runtime today
not a browser plugin
not a raw fork product of any upstream repo

V1 Scope

Switchyard V1 is intentionally narrow:

BYOK
Web/Login

Current Web/Login provider set:

ChatGPT
Gemini
Claude
Grok
Qwen

Current BYOK code support must cover:

OpenAI
Anthropic
Grok / xAI
OpenRouter
Groq
Qwen API
Vertex AI
Bedrock

Explicit non-goals right now:

Agent Input Lane
Codex / Claude Code as supply-side sources
Gemini CLI
shared public credentials
multi-tenant account pooling
a hosted control plane

Architecture In One Sentence

Switchyard separates lane, provider, consumer, and surface so
that the runtime stays reusable even while builder routes and public claims stay
fail-closed.

High-level shape:

flowchart LR
    A["BYOK lane"] --> K["Switchyard kernel"]
    B["Web/Login lane"] --> K["Switchyard kernel"]
    K --> H["HTTP service surface"]
    K --> S["SDK surface"]
    H --> F["First-party integrations"]
    S --> D["Future AI app consumers"]
    H --> C["Future consumer compat"]

What Ships Now vs Later

Ships now

service-first runtime surface
partial read-only MCP surface
partial thin compat packages
runtime-diagnostics public skill packet
starter packs and host examples
proof-first docs atlas and public distribution ledger

Still later

official marketplace listings
official MCP Registry listing
npm publication read-back
Docker/runtime catalog publication
hosted multi-tenant runtime
full consumer parity
write-capable MCP

Proof And Reality Truth

Live/browser outcomes are important, but they are proof / runbook truth for a
credentialed workstation, not the stable repo identity.

That means:

repo-side green does not erase local browser/session blockers
one workstation result should not rewrite the top-level product sentence
current live/browser reality belongs in
docs/public-proof-pack.md
and docs/runbooks/dev-bootstrap.md

Use the proof pack when the question becomes:

what is really proved today
which blockers are external-only
which results depend on local credentials and browser session materials

Distribution Truth

Current distribution truth is intentionally narrow:

GitHub Pages storefront is live and remains the primary public homepage
repo materials are package-ready for the MCP surface and thin compat packages
official marketplace or registry publication is not claimed yet
builder packets and starter packs are public repo surfaces, not official
listings
packet-scoped host receipts, including the
switchyard-runtime-diagnostics packet, belong in the packet's own manifest
and README; they do not upgrade repo-wide npm, marketplace, or official
MCP Registry truth

See:

If you need the exact heavy-lane packet or older staging material, treat them as
deeper shelves rather than the default first stop.

Docs Atlas

First-row public routes

Deeper public shelves

Internal-only working packs

Wave 1 contract/evidence packs now live under .agents/internal-docs/wave1/.
The old docs/blueprints/wave1/* locations remain only as relocation notes so
older links do not break.

Truth Rules

supported means there is a durable, repo-backed public surface now.
partial means a real narrow slice exists, but it is not the full promised
shape.
planned means the route is intentional but not landed.
research means investigation exists but support does not.
not now means the surface is explicitly outside the current public front
door.

Security And Local Runtime Boundaries

Do not publish cookie bundles, browser profiles, or other credential
materials.
.runtime-cache/, .agents/, and .env* stay out of public release
surfaces.
Repo-local cleanup only applies to Switchyard-owned runtime artifacts, never
to machine-wide caches or other apps.
Before live/browser/cleanup actions, run:
```
pnpm run scan:host-process-risks
```

For local runtime hygiene, browser/session acquisition, and operational
footprint, go to docs/runbooks/dev-bootstrap.md.

Verification Entry Points

pnpm run typecheck
pnpm run test:coverage
pnpm run test:docs-frontdoor
pnpm run build

One Final Sentence

Switchyard exists because AI apps should share one honest provider runtime
instead of each product rebuilding the provider layer alone.