# Boogy — agent quickstart

Boogy is a backend platform: services are Rust compiled to `wasm32-wasip2`,
deployed to a shared runtime with isolated transactional storage,
capability-based security, auth, rate limiting, cross-service calls, a
built-in MCP (Model Context Protocol) surface for LLM clients, and
host-served web frontends (ship a UI with no JS build step).

This file is self-contained: an agent reading only this can set up a
project, build it, and deploy it.

## Step 0 — read the Boogy skills first

The skills encode Boogy's hard invariants (transactions, data integrity,
capability-based security, the high-level SDK interfaces) and the design
patterns for a correct, secure, well-designed service. Read them before
writing code — two ways, neither needs a toolchain:

**Fetch them (no install — best when you're building right now):**

    https://boogy.ai/skills/using-boogy/SKILL.md   # entry — routes every task
    https://boogy.ai/skills/<name>/SKILL.md         # any `boogy:<name>` it references
    https://boogy.ai/skills.txt                      # the whole catalog, one fetch

**Vendor them locally (for a project you'll revisit):**

    boogy skills install              # Claude Code auto-discovers .claude/skills/
    boogy skills install --for auto   # also wire up Codex/Gemini (AGENTS.md / GEMINI.md)
    # or: npx degit Boogy-ai/boogy-superpowers/skills .claude/skills/boogy

The entry skill opens with a design-first gate (deployment shape → backend
kind → surface → capabilities → ingress → data) and routes every kind of
Boogy task (design, data modeling, auth, jobs, frontends, MCP/REST, deploy)
to the right skill. Any agent that reads markdown can follow them.

## Core concepts

- **service** — the deployable unit: a Wasm component owning a route
  subtree. Requests arrive at `/{owner_user_id}/{service_path}`.
- **manifest** — `boogy.toml` next to your crate: identity (`[service]`),
  routing (`[routing]`), capability grants (`[capabilities]`), resource
  caps (`[limits]`), access control (`[ingress]`).
- **capabilities** — deny-by-default grants: `store`, `auth`, `clock`,
  `entropy`, `logging`, `peer`, `outbound_http`, `background_jobs`,
  `signing`, `websockets`. Using one without granting it is a host error.
- **deployment shape** — pick before you build: **Service** (wasm backend,
  no UI), **Full-stack** (wasm API behind a host-served frontend, one
  origin), or **Frontend** (static site / SPA, no wasm). A `[frontend]`
  manifest block declares the UI; the platform transpiles TypeScript and
  serves the assets — no JS toolchain on you.
- **store** — isolated, transactional storage scoped to your service.
  Typed models via `#[derive(Model)]`; multi-row transactions available.
- **peer** — in-process calls to other deployed services (`peer::fetch`),
  no network hop.
- **MCP** — `boogy_sdk::mcp::McpServer` exposes typed tools to LLM clients
  alongside REST routes, over the same auth.
- **spec** — every deployed service auto-serves `GET <routes>/openapi.json`
  (OpenAPI 3.0.3); JSON-RPC mounts also serve `GET <routes>/openrpc.json`.

## Set up a project

Prerequisites: Rust stable (1.80+) and the wasm target:

    rustup target add wasm32-wasip2

Start from the `smoke/` template in the SDK repo:

    git clone https://github.com/Boogy-ai/boogy-sdk
    cp -r boogy-sdk/smoke/ my-service && cd my-service

Pin git deps in `Cargo.toml` (replace `<pin-rev>` with a commit SHA from
the repo's `main`):

    [package]
    name = "my-service"
    version = "0.1.0"
    edition = "2021"

    [lib]
    crate-type = ["cdylib"]

    [dependencies]
    boogy-sdk   = { git = "https://github.com/Boogy-ai/boogy-sdk", rev = "<pin-rev>" }
    wit-bindgen = "0.46"
    serde       = { version = "1", features = ["derive"] }
    serde_json  = "1"   # required: wit_glue! uses ::serde_json paths
    schemars    = "0.8" # required: #[derive(JsonSchema)] for spec generation

    [build-dependencies]
    boogy-wit = { git = "https://github.com/Boogy-ai/boogy-sdk", rev = "<pin-rev>" }

The template's `build.rs` syncs WIT files from the pinned `boogy-wit` into
`wit/` (generated — gitignore it; it never drifts from your SDK revision).

Minimal `src/lib.rs`:

    mod bindings {
        wit_bindgen::generate!({
            world: "service",
            path: "wit",
        });
    }

    boogy_sdk::wit_glue!(bindings, MyService);

    use boogy_sdk::Api;

    struct MyService;

    impl Api for MyService {
        fn build_router() -> Router {
            Router::new().get("/api/ping", ping)
        }
    }

    #[derive(Serialize, schemars::JsonSchema)]
    struct Pong {
        message: &'static str,
    }

    fn ping(_req: &mut Req<'_>) -> Json<Pong> {
        Json(Pong { message: "pong" })
    }

## Build

    cargo build --target wasm32-wasip2 --release

Artifact: `target/wasm32-wasip2/release/my_service.wasm` (cargo replaces
`-` with `_`).

## Manifest

Create `boogy.toml` in the crate root:

    [service]
    id = "my-service"
    name = "My Service"
    version = "0.1.0"
    wasm = "target/wasm32-wasip2/release/my_service.wasm"
    # owner is a bare optional key (owner = "handle"), NOT a [service.owner]
    # table — and you normally omit it: the platform sets it to your
    # authenticated handle at deploy. wasm is optional too: omit it for a
    # frontend-only ([frontend], no wasm) deployment.

    [routing]
    path = "/api/ping"
    methods = ["GET"]

    # [capabilities] and [limits] are OPTIONAL — omit to grant nothing /
    # take defaults; declare them to grant capabilities or override limits.
    [capabilities]
    store = false

    [ingress]
    mode = "public"   # public | authenticated | allowlist | internal | mixed

Full field reference (limits, rate limits, outbound HTTP policy, secrets,
background jobs):
https://github.com/Boogy-ai/boogy-sdk/blob/main/docs/manifest.md

## Sign in

To deploy you need a token. Two paths — MCP is zero-install and the natural
fit when your agent is already connected to Boogy's MCP server:

**MCP (primary — no install):**

1. Call the `login` tool. It returns a `user_code`, a verification URL, and a
   `device_code`.
2. Show the human the URL and `user_code`. They open the URL, sign in with a
   provider (Google / GitHub / …), and confirm the on-screen code **matches**
   the one you showed them (anti-phishing step).
3. Poll `login_status` with the `device_code` every few seconds until it
   returns `{status: "complete", token: "v4.public.…"}`. Use that token.

**CLI (alternative — requires the CLI):**

    boogy login

`boogy login` runs the same device flow, opens the browser automatically, and
saves the token to `~/.config/boogy/credentials.toml` (0600). Later CLI
commands load it automatically; no `BOOGY_TOKEN` export needed.

## Deploy

    cargo install --locked --git https://github.com/Boogy-ai/boogy-sdk boogy-cli
    export BOOGY_TOKEN=v4.public.<your-token>   # from boogy login or the MCP login flow
    boogy deploy boogy.toml
    curl <host>/your-user-id/api/ping

The CLI targets `http://localhost:3000` by default; override with
`BOOGY_HOST_URL` or `--host`.

Platform API reference: `GET <host>/openapi.json` — OpenAPI 3.1 self-description of the full deploy lifecycle (`/_agents/*`, `/_admin/*`, `/v1/*`); anonymous fetch OK.

## Serving a frontend (full-stack or frontend-only)

Boogy serves a web UI for you — no bundler, no Node, no JS toolchain. You
ship TypeScript/JS/HTML/CSS source; the control plane transpiles and serves
it from object storage. Add a `[frontend]` block:

    [frontend]
    root = "web"          # source dir: index.html + .ts/.css/assets
    api_prefix = "/api"   # full-stack: requests under it → wasm; omit for frontend-only
    build = "ts"          # "ts" (platform transpiles) | "none" (pre-built assets)
    private = false       # true gates the UI behind the service ingress

Shape derives from what you ship: `[frontend]` + wasm → full-stack;
`[frontend]`, no wasm → a frontend-only static site / SPA; no `[frontend]`
→ a plain service. Frontend assets carry an always-on security-header
baseline; `csp` and `frame_options` are opt-in. For cross-origin API
callers, allow them with `[ingress.cors]` (default-deny). Full guidance:
the `boogy-serving-frontends` skill.

## Going further

- Handler authoring (routers, guards, store access, auth patterns, MCP
  tools): https://github.com/Boogy-ai/boogy-sdk/blob/main/crates/boogy-sdk/AGENTS.md
- Five-step quickstart with full explanations:
  https://github.com/Boogy-ai/boogy-sdk/blob/main/docs/quickstart.md
- Skill catalog (29 skills: design, scaffolding, testing, deploying, data
  modeling, access patterns, migrations, transactions, auth, account auth,
  capability limits, OBO delegation, REST APIs, API specs, MCP services,
  serving frontends, websockets, signing, inbound webhooks, background jobs,
  observability, registry/provisioning, service lifecycle, mesh
  architecture, performance/scaling, secrets, outbound HTTP):
  https://github.com/Boogy-ai/boogy-superpowers