slave

A Laravel-inspired Rust framework for MCP-first applications.

Every business operation in a slave app is an MCP tool served over Streamable HTTP, so AI agents and your own web apps use the same, single API. The slave CLI scaffolds the backend (users, roles, OpenID Connect sign-in, Toasty models and migrations on PostgreSQL), adds server-rendered web apps (MiniJinja, Tera, Handlebars or Liquid templates), and serves them all from one process routed by domain or path (any app can also run as a process of its own, proxied), in the spirit of laravel new, php artisan make:* and Route::domain().

browser / AI agent
        │
        ▼
runtime (one process) ── config/apps.toml: route by domain and/or path
   ├──► MCP backend      /mcp: auth_*, user_*, role_*, your tools …   ← owns the database
   └──► apps/storefront  theme, server-rendered templates              (calls MCP tools in-process)

Why

• One interface. No REST layer next to MCP: the tools an AI agent calls are the same ones your dashboards call.
• Batteries included, security delegated. Users and roles, sign-in through any OpenID Connect provider (no passwords stored, ID tokens verified on every call), Toasty models on PostgreSQL with migrations generated from them, tests that drive /mcp end to end with a throwaway database per test and a built-in test identity provider.
• Pick a template language per app. Server-rendered pages (MiniJinja, Tera, Handlebars or Liquid) for a storefront theme or an admin area; apps reach the backend only through MCP.
• Laravel ergonomics. Generators, optional domain and path routing, route:list, slave build then one slave serve for everything.
• Agent-ready projects. Every new project ships an AGENTS.md (and a CLAUDE.md that imports it) teaching coding agents the architecture, the rules and recipes for adding features.

Install

cargo install slave

Requirements: Rust 1.85+. Deploying to Fly.io needs the Fly CLI.

Quick start

slave new shop && cd shop
slave migrate                                            # users and roles in DATABASE_URL (set it and OIDC_* in .env first)
slave make:app storefront --domain "{toko}.localhost"    # theme per store
slave build                                              # first build takes a while; later ones seconds
slave serve

Everything runs in one process, the runtime (runtime/). Without --domain/--path, an app is served directly on its own port (still in that process). make:app --separate or app:separate <app> runs an app as a process of its own, proxied by the runtime, to deploy or scale it separately.

  MCP backend   http://127.0.0.1:3000/mcp
  Runtime       http://127.0.0.1:8000  (one process)
    http://mcp.localhost:8000            → MCP backend
    http://<toko>.localhost:8000         → storefront

The first user to sign in through your OpenID Connect provider becomes admin. MCP clients send the provider's ID token, for example Claude Code:

claude mcp add --transport http shop http://mcp.localhost:8000/mcp

(with --header "Authorization: Bearer $ID_TOKEN"), or sign in through one of the apps.

Commands

Database

The backend keeps the platform's own data (users, roles, and what you add) in PostgreSQL: set DATABASE_URL in .env, create the database once (createdb <name>, or use a hosted one such as Supabase or Neon), then slave migrate. Web apps never open it; they call MCP tools. Tests create a fresh database per test on TEST_DATABASE_URL (default postgresql://localhost:5432/postgres) and drop it afterwards.

Deploying to Fly.io

fly auth login
cp .env .env.production                        # then edit it for production
slave install:fly --app tokoku --domain example.com   # optional: deploy:fly runs it if needed
slave deploy:fly --secrets .env.production
fly certs add "*.example.com" --app tokoku     # one per host install:fly prints

install:fly writes a Dockerfile, fly.toml and config/apps.fly.toml (your routes with localhost moved under --domain). deploy:fly creates the app, stages the env file as Fly secrets, refuses to deploy while a required secret is missing, and runs fly deploy; pending migrations run first (release_command). Machines are stateless, so fly scale count 2 works. Environment on Fly:

Set by the image, do not override: APP_HOST, APP_PORT, GATEWAY_LISTEN (0.0.0.0:8080), SLAVE_ROUTES (config/apps.fly.toml) and SLAVE_TRUSTED_PROXY (1, so apps see https behind Fly's proxy). At each app's provider, register the redirect URI https://<its host><its path>/callback.

Routing

config/apps.toml maps requests to apps, like Laravel's Route::domain() and Route::prefix():

[[domain]]
host = "admin.localhost"      # by domain
app = "dashboard"
port = 4000

[[domain]]
host = "{toko}.localhost"     # {toko} reaches the app as X-Slave-Param-Toko
app = "storefront"
port = 4001

[[domain]]
path = "/console"             # by path, on any host (add `host` to restrict)
app = "console"
port = 4002

The most specific entry wins regardless of order: the longest path prefix, then the most specific host. Unknown routes get 404, a down app gets 502, and spoofed X-Slave-* / X-Forwarded-* headers are dropped.

Crates

Repository layout

src/          the slave CLI (commands, generators)
templates/    files written by `slave new` and `slave make:*`
framework/    slave-framework
gateway/      slave-gateway
tests/        end-to-end tests of the CLI and generated projects

Run the tests with cargo test --workspace; cargo test -p slave --test cli -- --ignored also builds a generated project and runs its own test suite.

License

MIT