Starter kits are ready-made Suprnova applications you fork and ship. Each one wires the controllers, routes, migrations, frontend pages, and tests for a complete product surface - so you start from a running app, not an empty scaffold.
Three kits ship, modelled on Laravel's lineage. Pick the one closest to what you're building and customise from there.
Nebula - authentication (Breeze-tier)
Repo: github.com/eas4ai/Nebula
The minimal full-auth kit - Suprnova's Breeze equivalent. Everything you need for accounts and nothing you don't:
- Registration with email verification
- Login with remember-me
- Password reset with anti-enumeration responses
- Profile management - update email and password, delete account
- A branded Inertia 3 + Svelte 5 frontend (dark by default), with the logged-in user menu wired
Nebula ships two test suites: facade-level auth logic, and a wire-level HTTP suite that drives real routes, sessions, CSRF round-trips, and the guest / auth / verified gates over a loopback socket.
Reach for Nebula when you want a clean account-management foundation to build your own product on top of.
Pulsar - product site & community
Repo: github.com/eas4ai/Pulsar
A complete developer-tool / SaaS company site on Vue 3.5 + Vuetify. Everything in Nebula's auth story, plus the surfaces a real product site needs:
- Marketing landing page and a user dashboard
- A Markdown documentation pipeline (
docs:build) with search and a generated table of contents - A blog / articles system with an RSS feed
- Public member profiles
- Taxonomy - topics, tags, and categories
- Role-based access control: roles, permissions, and gates
- Admin and moderation surfaces for content and members
Pulsar is the source kit for downstream products such as suprnova.app. Reach
for it when you're shipping a product site with docs, a blog, and a member
community - not just authentication.
Directory starter - listings, moderation, and paid publication
Repo: github.com/eas4ai/suprnova-directory-starter
A free, MIT-licensed directory on Vue 3.5: owners submit listings, moderators review them, visitors search them, and publication is free or paid through Stripe and Paddle. Everything in Nebula's auth story, plus:
- Directory discovery - searchable listings, category filters, pagination, and public detail pages
- Owner submissions and moderation - drafts, revision history, approval, rejection, resubmission, and suspension
- Free and paid publication - Stripe and Paddle, configurable plans, separate test and live settings, authenticated webhooks, and payment recovery
- Editorial publishing - article drafts, previews, categories, tags, and RSS
- Administration - permission-based roles, account suspension, audit history, and an admin overview
- SEO - site defaults and per-content overrides, server-rendered metadata, sitemaps, redirects, a 404 report, and Markdown versions of public pages
- Media and notifications, colour presets with a remembered light or dark preference, demo content, and documented backup and restore workflows
Reach for the directory starter when the product is a directory or a marketplace of listings, with or without paid placement.
Which kit?
| You want… | Start with |
|---|---|
| Accounts and a place to build | Nebula |
| A full product site - landing, docs, blog, community, RBAC | Pulsar |
| A directory or marketplace of listings, free or paid | Directory starter |
| Server-rendered pages with no Bun toolchain | suprnova new my-app --frontend live |
| An API-only backend (token auth, no frontend) | suprnova new my-api --api |
All three kits track the framework as a git dependency and run on the same stack you already know - see each repo's README for setup. More kits are planned; watch the releases or open an issue if there's one you want.
What the default scaffold gives you
If neither kit fits, suprnova new my-app --frontend svelte (or react, or
vue) already ships a working authentication flow - login, register, logout,
email verification, password reset, session authentication with the
authenticate middleware, CSRF protection, and a protected /dashboard
route - on any of the three frontends (Svelte 5,
React 19, Vue 3.5) with Tailwind v4 and Inertia v3, or on the
Live starter kit, which needs no Bun toolchain. See
Installation for the scaffold output and
Quickstart for the first-five-minutes walkthrough.
Behind the authentication group, the scaffold ships the server side of the kit pages, all of it over the signed-in user's own data:
- A
notestable and aNotemodel (src/models/note.rs) that belongs to a user, withNote::owned_by(user_id)as the one way the handlers read notes. GET /dashboard, which sendsstatsdeferred (the user's note count and the notes written today) andrecent_notesoptional (the user's five newest notes).GET /notes, which lists the user's notes 10 at a time withcursor_paginatethroughInertia::paginate, filtered by thesearchquery parameter in title or body without regard to case, and sendssearchback to the page.GET /notes/{id}, which shows one of the user's notes and answers404for a note of another user or an id that doesn't exist.POST /notes, which validatestitle(1 to 255 characters) andbody(at most 10000 characters), writes the note, flashes a toast, and returns to the page the form was posted from, preserving its search query, with/notesas the fallback.POST /profile/name, a JSON handler for the dashboard's name form that answers200with{"user": {...}}or422with the framework's validation body.
Every page receives the signed-in user, or null for a guest, under the
shared auth prop: bootstrap.rs shares it with App::inertia_share_lazy,
which reads the request's session for each response that sends it, and
SharedData in src/props/shared.rs, marked #[inertia_props(shared)],
adds auth to the generated SharedProps. A layout reads
usePage().props.auth.user.
Sign-in, registration, a reset-link request, a password reset, email
verification, a verification resend, sign-out, and a saved note each flash a
Toast (src/props/flash.rs) under the key toast. The Flash struct
beside it holds that toast and is marked #[inertia_props(flash)], so
suprnova generate-types names it as Inertia's flashDataType and
page.flash.toast is typed in every page.
The routes carry the names Laravel's kits give them: dashboard,
notes.index, notes.show, notes.store, profile.name, login,
register, password.request, password.email, password.reset,
password.update, verification.notice, verification.send,
verification.verify, and logout.
The dashboard handler shows how each prop travels:
pub async
Live note updates
The Inertia kits also keep the dashboard's stats current when a note is
saved or deleted. Their Live registry declares a private topic family,
live::authorize() defines its audience, bootstrap calls it and connects
model hooks, and the dashboard props bind stats to it:
// src/live/mod.rs
let registry = builder.topic_family?.build;
// src/bootstrap.rs
crateauthorize;
singleton;
resolve?
.?;
// src/controllers/dashboard.rs
.scope
.load_with
.await?
.resolve
.await?;
Each frontend mounts its small useLive() adapter on Dashboard. A signal
asks Inertia to reload only stats; the controller recalculates it over the
signed-in user's own notes. Only the owner receives the instance signal or its cursor. The signal carries
no note values. The baseline is captured before the loader runs. usePoll
remains as the fallback when the browser cannot keep a push transport open.
See Live topic bindings for the page
contract and Topic signals for publication rules.
Why Suprnova diverges
Laravel's Inertia kits do not include topic bindings. Suprnova's kits register
the note topic and install each frontend's adapter. They keep usePoll so
the dashboard updates when push delivery is unavailable.
The Svelte kit's pages show Inertia 3.8's client components at work:
layouts/AppLayout.svelteandlayouts/GuestLayout.svelteframe every page throughcreateInertiaApp'slayoutoption and stay mounted across visits. They carry theLinknavigation, the signed-in user's name and a sign-outLink(or sign-in and register links for a visitor), and the toast a handler flashes, whichcomponents/FlashToast.sveltereads frompage.flash.Dashboardloads the note counts withDeferred, refreshes them from thenotesLive topic, and keepsusePollas a fallback. It loads the recent notes withWhenVisibleonce they scroll into view and sets the layout's heading withsetLayoutProps. Its display-name form posts JSON throughuseHttpand shows the new name before the server answers.Notes/Indexcreates a note with theFormcomponent, keeps its search box withuseRemember, loads more notes withInfiniteScroll, and opens a note with a prefetched, instantLinktoNotes/Show.- The pages under
auth/submit through theFormcomponent, and every page titles its tab with the kit'scomponents/Head.svelte.
For the code, see Page Components.
The React starter (--frontend react) runs on Inertia 3.8 through the
@inertiajs/vite plugin and shows the client side of each feature on a
page you can copy. Dashboard renders stats with Deferred, refreshes it
from the notes Live topic with usePoll as a fallback, loads
recent_notes with WhenVisible, and changes your display name through
useHttp with an optimistic update. Notes/Index
creates a note with Form, remembers its search with useRemember,
scrolls your notes with InfiniteScroll, and opens one with an instant,
prefetched Link; Notes/Show renders it. Login, Register,
ForgotPassword, ResetPassword, and VerifyEmail submit through Form.
Every page sets its title with Head, and the pages render inside a
guest layout (the auth/ pages) or an application layout (the rest). Both
show the flash toast and, from the shared auth prop, the signed-in
user's name and a sign-out link or the sign-in and register links. See Page Components for the
code.
The Vue kit (--frontend vue) runs on Inertia 3.8 and its Vite plugin, and
each page shows part of the client at work:
Dashboard.vueloads the note counts as a deferred prop withDeferred, refreshes them from thenotesLive topic withusePollas a fallback, loads the recent notes withWhenVisible, and saves the display name throughuseHttpwith an optimistic update.Notes/Index.vuecreates a note withForm, remembers its search withuseRemember, scrolls the signed-in user's notes withInfiniteScroll, and opens a note as an instant visit from a prefetchingLink.Notes/Show.vueshows one of the signed-in user's notes.- The five pages under
auth/submit throughForm. layouts/AppLayout.vueandlayouts/GuestLayout.vue, applied through thelayoutoption, carry the navigation, the flash toast fromcomponents/FlashToast.vue, and the account links fromcomponents/AccountLinks.vue: the signed-in user's name and a sign-out button, or the sign-in and register links for a guest. Every page titles its tab withHead.
Static publication
All three Inertia kits install src/lib/static/index.ts through
createInertiaApp's http option. Their adapters share the same
src/lib/static/core.ts. Without publication metadata the original
Inertia XHR transport runs unchanged.
A published document supplies its asset version in
<meta name="suprnova-static-version" content="..."> and its concrete
public page paths in the JSON script suprnova-static-pages. Navigation
between those pages reads the versioned JSON object the map names. The
browser history keeps the page's canonical URL. A different asset version
reloads that canonical document. A full visit to a path absent from the map
reaches its canonical origin URL, where a marked public page can be published
on its first visit.
Partial reloads, polling, deferred props, once props, queries and mutations
use the original route with ?__suprnova_origin=1. Existing query values
are kept. This URL bypasses publication, and both the request and response
carry Cache-Control: no-store. Flash and validation errors are accepted
from this private origin response; a published object containing either
falls back to the origin.
Before a mutation from a published document, the client obtains the
same-origin XSRF-TOKEN cookie from a private origin request if it is
missing. Inertia's XHR client reads the current cookie for every request
and sends it as X-XSRF-TOKEN, including after a sign-in rotates it. No
session token is embedded in a published document.
Agents in the Inertia kits
The React, Vue and Svelte kits serve agents from the first
cargo run: the MCP endpoint at /mcp, the OAuth server an MCP client signs
its user in through, and agent accounts under auth.md. src/agents.rs turns
them on, and cmd/main.rs serves the routes through agents::serve. The
kit replaces the framework's three default pages with its own, rendered by
src/controllers/agents.rs in the kit's frontend:
The browser helpers use the community's webmcp-types 0.1.10 definitions,
pinned in devDependencies, to check their registrations and annotations.
| Page | Route | What the user does there |
|---|---|---|
Agents/Approve |
GET /oauth/approve |
Allows or denies an MCP client. The page names the client, its host, every permission it asks for and the address the user returns to. |
Agents/Claim |
GET /agent/claim |
Lets an agent act for them, with the code the agent gave them. A wrong code comes back as the field's error with the attempts left. |
Agents/Connected |
GET /connected-agents |
Sees and revokes every app and agent that acts for them. The app layout links it as Agents. |
The paths of the first two are the framework's defaults, so a link a client
or an agent holds opens the same page with or without the kit. A guest who
opens either one signs in and comes back: the sign-in page keeps a
return_to that is a path on this application, and a registration in the
same session keeps it too. A return_to that a browser would read as
another site, such as //evil.example, is ignored, and the user goes to the
dashboard.
The pages read and record what the user decides through AgentApprovals,
AgentClaims and ConnectedAgents, which act for the signed-in user only.
Approving a client needs a signed-in user, as the dashboard does. Claiming
an agent needs the address the agent named, verified: the claim page tells
an unverified user to verify first. A few rules hold on every page:
- Each route runs
ConsentPageHeaders, so another site can't frame the page, and no cache or referrer keeps the authorization id or the claim's attempt token. The rest of the security headers policy, its nonce among it, stays asSecurityHeaderssets it. - The global CSRF middleware checks every form.
- A decision leaves for the client by a location visit
(
Inertia::location), which the browser follows itself. A redirect that answers the form would be blocked by the policy'sform-action 'self'. - No page offers a tool, and no consent route declares one, so an agent in
the browser can never approve a client or claim itself. A form tool marks
the form it submits with the
Suprnova-Form-Toolheader, and the pages refuse it with a 403, so even a form tool an application adds to one of them cannot approve or claim. - Text a client, an agent or the user chose sits in
<bdi>, and no page renders raw HTML or loads a URL the client chose.
suprnova new writes a signing key for agent auth into .env, as
AGENT_AUTH_KEY_ID and AGENT_AUTH_PRIVATE_KEY. The application doesn't
start without one. Every other environment needs its own key, so a deploy
that doesn't copy .env, such as the production image, sets both
variables. cargo run -- agents:key prints a new pair. For rotation, see
Keys and operations.
The kit ships two tools on the signed-in user's own
notes, so the MCP endpoint has something to list from the first run.
src/controllers/note_tools.rs defines them, and src/agents.rs declares
their scopes with tool_scopes!, in
agents::scope:
| Tool | Route | Scope | What it does |
|---|---|---|---|
search_notes |
GET /notes/search |
notes:read, "Read your notes" |
Finds the user's notes by the words in their titles and text, best match first, or lists the newest. It takes query, up to 200 characters, and limit, 1 to 50 and 10 when left out. |
create_note |
POST /notes/tools |
notes:write, "Write notes for you" |
Writes a note for the user, with the notes form's rules: a title of 1 to 255 characters and an optional body of up to 10000. It answers the note. |
Both tools accept users and agents, and each call acts for one user: the
one signed in, the one who approved the client, or the one who claimed the
agent. A client's token holds the scopes the user allowed on the approval
page, which shows each scope by its description. An agent holds both scopes
once a user claims it, and none before: an agent no user has claimed gets a
403 with insufficient_scope. search_notes is marked read_only and
untrusted_content, because it hands back note text, which the user wrote
and an agent must not take as instructions.
The notes page offers both tools to an agent in the user's browser, through
.with_tools(["search_notes", "create_note"]) on its route. It is the only
page that offers a tool, and a guest is never offered either. After
create_note,
the page reloads its props, so the list shows the new note.
frontend/src/types/tool-schemas.ts carries both inputs, as
SearchNotesInput and CreateNoteInput.
To call the tools from Claude Code, run the project with suprnova serve
and add its endpoint, over the Streamable HTTP transport, at the URL
APP_URL names in .env:
Claude Code connects without a token and lists both notes tools. Calling
one answers 401, and Claude Code reports that the server needs you to sign
in; run /mcp to sign in. The client gets its token from the kit's OAuth
server: it registers, sends you to the approval page to allow the scopes it
asks for, and from then on lists the tools those scopes reach. A token with
notes:read alone sees search_notes and not create_note. See
Users who approve a client.
Why Suprnova diverges
Laravel's starter kits ship a dashboard with placeholder content and no list page. Suprnova's scaffold lists the signed-in user's own notes, so deferred and optional props, cursor scrolling, a JSON form, and flashed toasts each have a working server to talk to. No handler lists accounts: a directory of users would show every member the name and email of every other member.
The API kit
For API-only services, suprnova new my-api --api initializes Magnetar,
installs bearer-session middleware, and scaffolds password registration and
login against the canonical app_users table without a frontend.
Agents in the API kit
suprnova new my-api --api serves agents from src/agents.rs: the MCP
endpoint at /mcp, the OAuth server that MCP clients sign users in through,
and agent accounts under auth.md. For what each of these does, see
Agents. The kit has no frontend, so it serves the framework's
own pages, which are plain HTML with no script:
| Page | Path | What the signed-in user does there |
|---|---|---|
| Approval | /oauth/approve |
Allows or denies an MCP client |
| Claim | /agent/claim |
Enters the code an agent gives them |
| Connected agents | /oauth/connected |
Sees and revokes the clients and agents that act for them |
src/agents.rs names each path once, as a constant, and gives the same
constants to the OAuth server, agent auth, the sign-in page and the session.
The consent sign-in
A person approves a client or claims an agent in a browser, so these pages
act for the user of a browser session. The kit signs a browser in at
/login (src/controllers/sign_in.rs) for them:
- A guest who opens the approval or claim page is sent to
/login?return_to=.... - The guest signs in with their email address and password, through
Auth::password(). - The page continues to the address in
return_to. Only a path on this application is kept: an address such as//evil.exampleorhttps://evil.examplesends the user to/oauth/connectedinstead.
The page is fixed markup with one value in it, the session's CSRF token. Its
routes carry ConsentPageHeaders, so it is never framed, cached, or sent as
a referrer, and its form posts through the route's CsrfMiddleware. An
account with a second factor is told that the page does not offer one, and
stays signed out. To let those users approve clients, add the factor
challenge to the page.
Email verification
A claim needs the user's email address verified, so the kit verifies it with
a link, through Auth::email_verification()
(src/controllers/email_verification.rs):
- Registration mails a new account the link, once. Registering an address
that already has an account mails nothing.
POST /api/auth/registertakes six requests a minute from one client address, and answers429past that. - A signed-in client asks for a new link with
POST /api/email/verification-notification. It answers202when it mails one, and204when the address is already verified. The route takes six requests a minute, and one address gets at most three links an hour, the registration's included; past either it answers429. - The link opens
/email/verify?token=...in a browser. A guest is sent to/loginand comes back, and the page then verifies the address of the user signed in there.
The link works once and expires after 24 hours. It verifies only for the
account's own user: anyone can register another person's address with a
password of their own, and a link that verified whoever opened it would
verify that account. It also proves only the address it was mailed to: once
the account's address is another, the page answers 409 and verifies
nothing, and the user asks for a new link. Verifying with one link spends
the account's other links. Verifying changes no credential and starts no
session. The mail comes from MAIL_FROM, and names the application as
APP_NAME.
A new API project's .env mails as the other kits' does: through a local
SMTP catcher on port 1025 (maildev, mailpit or mailhog), from
hello@example.com. Set a real relay and sender for production, which
refuses an unencrypted connection. When the link cannot be mailed,
registration still answers 202 and logs the failure, and the resend
route answers 500.
Sessions on the consent pages only
bootstrap.rs registers agents::ConsentSession, which runs the session
middleware on these paths and no others:
/login, the sign-in page, and its form./logout, where the sign-out form posts./oauth/authorize,/oauth/approveand/oauth/authorizations/{id}, where a user approves a client./oauth/connectedand the revoke forms under it./agent/claimand its form./email/verify, the page the verification link opens.
Every other route serves a client of the JSON API, an MCP client, or an
agent, which sign in with a bearer token: /api/*, /mcp, the
/.well-known/* documents, the token, registration and revocation
endpoints, and agent auth's JSON routes. None of them starts a session or
sets a cookie, so no client or agent can create a session row per request,
and the JSON sign-in at POST /api/auth/login returns a token and nothing
else. The migrator creates the sessions table, and the session settings
are the SESSION_* variables in Environment variables, with
two exceptions. A consent session ends after 15 minutes without a request
(agents::CONSENT_SESSION_IDLE), and its cookie has no expiry, so the
browser drops it when it closes. The kit adds no global CSRF middleware, so
the JSON API still takes no token.
A signed-in user ends the session at once with the Sign out form, which
posts to /logout with the session's CSRF token. The form is on the email
verification page, the page a signed-in user sees: /login sends a user who
is already signed in straight on. Signing out ends the session, and the next
approval or claim asks for a sign-in again.
bootstrap.rs also registers a DatabaseUserProvider over app_users, so
Auth::user() finds the user a bearer token or a consent page's session
signed in.
Connected agents over JSON
A client of the JSON API lists and revokes the same connections as the
connected-agents page. The routes sit behind AuthMiddleware beside the
user directory, and act for the user of the bearer token from
POST /api/auth/login:
| Route | Answer |
|---|---|
GET /api/connected-agents |
200 with {"clients": [...], "agents": [...]}, each newest first |
DELETE /api/connected-agents/clients/{grant} |
204, or 404 with {"message": "No such connected app."} |
DELETE /api/connected-agents/agents/{registration} |
204, or 404 with {"message": "No such connected agent."} |
An id that belongs to another user answers 404. An MCP access token is
not a sign-in to this API, so it gets 401 here. Revoking takes DELETE,
never POST: a plain form on another site can send POST, and the JSON
API runs no CSRF check. For the fields of each entry, see
Connected agents.
The signing key in production
suprnova new writes a signing key for agent auth into .env as
AGENT_AUTH_KEY_ID and AGENT_AUTH_PRIVATE_KEY. A deploy that does not
copy .env must set both variables, and the application does not start
without them. To print a new pair, run cargo run -- agents:key. Outside
the local and testing environments, also set APP_URL: it is the OAuth
server's issuer. For more about keys, see
Keys and operations.
Why the kit ships no browser helpers
The Inertia kits ship browser helpers that offer a page's tools to an agent in the browser (see Tools in the browser). The API kit has no pages of its own to offer tools on, so it ships none. An application that adds a frontend adds the helpers with it.
The Live starter kit
suprnova new my-app --frontend live scaffolds the same application as the
Inertia kits without a frontend build: no frontend/ directory, no
package.json, and no Bun toolchain. Every page is a server-rendered
Live document. The application serves the Live browser runtime
under /__live/assets/ and the library components' stylesheets and scripts
under /suprnova-ui/, so the backend is the only process you run.
The kit keeps the backend the Inertia kits share: the users and notes
tables and models, Note::owned_by(user_id) as the one way to read notes,
the account flows through Auth, PasswordReset, and
EmailVerification, and the route names. Pages render and act through Live
instead of Inertia:
| Page | Route | Layout | Live components |
|---|---|---|---|
| Welcome | / |
application | none |
| Sign in | /login |
guest | LoginForm |
| Register | /register |
guest | RegisterForm |
| Forgot password | /forgot-password |
guest | ForgotPasswordForm |
| Reset password | /reset-password |
guest | ResetPasswordForm |
| Verify email | /verify-email |
guest | VerifyEmail |
| Dashboard | /dashboard |
application | NoteStats, ProfileName |
| Notes | /notes |
application | NoteForm, NoteList |
| A note | /notes/{id} |
application | none |
| Error | any failed request | application | none |
The forms on the guest pages are public seeds, which any visitor can use.
Every other island is identity-bound: it belongs to the signed-in user, and
its route sits behind the auth middleware.
Files
The kit adds these files to the shared backend:
src/controllers/- one controller per page. Each opens the request'sLiveDocument, mounts the page's islands fromlive::mounts(), and renders the page's view.src/views/mod.rs- the view structs andFrame, the part both layouts read: the title, the Live bootstrap tags, the signed-in user, the CSRF token of the sign-out form, and the toast.templates/live/layouts/-guest.htmlfor the account pages andapp.htmlfor the rest, with the header bar, the account menu, and the toast region.head.htmlholds the bootstrap tags and the stylesheet links both layouts include.templates/live/pages/- one template per page. Each starts with{% extends "live/layouts/app.html" %}or the guest layout.src/live/andtemplates/live/*.html- the Live components and their views, registered insrc/live/mod.rs.templates/suprnova-ui/- the library components the views import, installed the waysuprnova live:addinstalls them and recorded insuprnova.toml, so a laterlive:addkeeps them current.src/flash.rs- theToasta finished flow shows on the next page.src/controllers/errors.rs- theErrorPagemiddleware, which renders every framework error response as the error page in the application layout, keeping the response's status, its other headers and its error report. A client that expects JSON keeps the JSON body, and in debug mode a5xxkeeps the development error page.src/controllers/profile.rs-POST /profile/name, the JSON endpoint the Inertia kits ship for the display name; the dashboard's island saves it through Live.public/css/app.css- the page layout, written with the same--sn-tokens the library uses.
What each component does
LoginForm,RegisterForm,ForgotPasswordForm, andResetPasswordFormcheck their fields with the same rules as the Inertia kits' form requests and show each message under its field. An action that succeeds signs the user in, mails a link, or rotates the password, then sends the browser to the next page with a toast.VerifyEmailnames the address the link went to and mails a new link on request.NoteStatsshows the user's note count, the notes written today, and the five newest notes. It subscribes to the streamnotes/:principal, which Live fills with the user's own id. Saving a note publishes a refresh on that topic, so every dashboard the user has open renders again without a page load, over server-sent events or a WebSocket, and through polling when neither connects. Its Refresh button renders it again on request.ProfileNamechanges the display name and reloads the dashboard, so the navigation shows the new name.NoteFormchecks the title (1 to 255 characters) and the text (at most 10000 characters), saves the note, and reloads the list with a toast.NoteListfilters the notes by title and text. The applied search is bound to the?search=query: each search puts it in the address bar without a history entry, and the page mounts the list from it, so a reloaded or shared URL shows the same list. Load more adds 10 notes at a time.
A finished flow keeps its Toast in the session, and the next document
takes it with Toast::take(), which removes it. The toast is an ordinary
session value rather than a session flash, because a flash ages on every
request of the session, the Live requests included. Saving a note makes
your open dashboards refresh, and that refresh would age a flashed toast
away before the redirect lands. The kit also turns session blocking on
(SESSION_BLOCK=true in .env), so the requests of one session run one
at a time and a refresh cannot write over the toast a save just kept.
Agents in the Live kit
The kit serves the MCP endpoint, the OAuth server that MCP clients sign
users in through, and agent accounts under auth.md, all from
src/agents.rs (see Agents). Three pages of its own let the
person decide what acts for them:
| Page | Route | What it shows |
|---|---|---|
| Approve an app | /oauth/approve |
The client, its host, each permission it asks for and where the user returns, with Allow and Deny |
| Claim an agent | /agent/claim |
The agent that asks to act as the user, the account it would act for, and a form that takes the code the agent gave them |
| Connected agents | /connected-agents |
Every MCP client and agent that acts for the signed-in user, each with a Revoke button |
The header and the account menu link the connected-agents page. The paths are the framework's defaults, so a link a client or an agent holds opens the same page with or without the kit.
These pages are plain server-rendered documents with native forms, not
Live documents. They mount no island and load no Live runtime, so no agent
in the browser is offered a tool that approves or claims: consent comes
from the person. Each form posts the session's CSRF token.
src/controllers/agents.rs reads and records each decision with
AgentApprovals, AgentClaims and ConnectedAgents, which act for the
signed-in user only. Another user's authorization reads as ended, and
their grants as unknown.
A guest who opens the approval or the claim page signs in and comes back
to it. A guest who registers instead comes back too, in the same browser
session. The address is not carried across email verification, and the
claim page asks an unverified address to verify first. A Live action can
only redirect to a named route, so the sign-in and registration forms
continue through /login/continue (login.continue), which follows the
address the session holds. A return_to that names another host is
ignored.
The routes run ConsentPageHeaders. No page or refusal here is framed,
cached or named in a referrer, since their addresses carry the
authorization id or the claim's attempt token. The kit's other security
headers stay, nonce policy included. That policy carries
form-action 'self', under which a browser blocks a redirect that answers
a form post on another origin. So Allow and Deny answer with a page
that sends the browser on to the client's redirect URI by a meta refresh,
with a link beside it. Every name, host and address a client, an agent or
the user chose sits in <bdi>, and no page shows a logo or links a page
the client chose.
suprnova new writes a signing key for agent auth into .env:
AGENT_AUTH_KEY_ID and AGENT_AUTH_PRIVATE_KEY. The application does not
start without them. .dockerignore keeps .env out of the image, so every
deployed environment sets both itself, each with a key of its own, and
names its public URL in APP_URL, which is the OAuth server's issuer. This
command prints a new pair and writes nothing:
tests/documents.rs renders the connected-agents page and the approval
page's refusal. A test process loads no .env, so the test calls
suprnova::testing::install_test_agent_auth_key() for a key made for the
process, and registers an AppConfig with a URL of its own. See
Agents for rotating the key.
Like the Inertia kits, the kit ships two tools on the
signed-in user's own notes, from the same src/controllers/note_tools.rs,
with their scopes declared by tool_scopes! in
src/agents.rs:
| Tool | Route | Scope | What it does |
|---|---|---|---|
search_notes |
GET /notes/search |
notes:read, "Read your notes" |
Finds the user's notes by the words in their titles and text, best match first, or lists the newest. It takes query, up to 200 characters, and limit, 1 to 50 and 10 when left out. |
create_note |
POST /notes/tools |
notes:write, "Write notes for you" |
Writes a note for the user, with the note form's rules: a title of 1 to 255 characters and an optional body of up to 10000. It answers the note. |
Each call acts for one user: the one signed in, the one who approved the
client, or the one who claimed the agent. A client's token holds the scopes
the user allowed on the approval page, and an agent holds both once a user
claims it and none before, so an agent no user has claimed gets a 403 with
insufficient_scope. search_notes is marked read_only and
untrusted_content, because the note text it hands back is the user's, not
instructions for an agent.
The notes page is the one page that offers tools: its route names both with
.with_tools(["search_notes", "create_note"]), and the document's head
carries them in its suprnova-agent-tools element, which the Live runtime
registers with WebMCP. A guest is never offered either. After
create_note, the runtime renders the page's islands again, so the list
shows the new note.
To call the tools from Claude Code, run the project with suprnova serve
and add its endpoint, over the Streamable HTTP transport, at the URL
APP_URL names in .env:
Claude Code connects without a token and lists both notes tools. Calling
one answers 401, and Claude Code reports that the server needs you to sign
in; run /mcp to sign in. The client gets its token from the kit's OAuth
server: it registers, sends you to the approval page to allow the scopes it
asks for, and from then on lists the tools those scopes reach. See
Users who approve a client.
Add a page
To add a page, give it a route, a view, and a controller:
- Add the route to
src/routes.rs, in the authenticated group if the page needs a user. - Add the view struct to
src/views/mod.rs, and its template totemplates/live/pages/, starting with the layout it extends. - Write the controller. Open the request's
LiveDocument, mount the page's islands, then build theFrame, which emits the bootstrap tags after the last mount, and render the view. - Declare the page in
live::routes()insrc/live/mod.rs: with.try_live_document("/path")?when it mounts no island, or with aLiveMountinMountsand.try_live_mount(&mounts.name)?for each island.
An /about page with no island looks like this:
// src/views/mod.rs
// src/controllers/about.rs
use LiveDocument;
use ;
use crate;
pub async
async
{% extends "live/layouts/app.html" %}
{% block content %}
About
{% endblock %}
Add a component
- Run
suprnova live:make Invoices. It writessrc/live/invoices.rsandtemplates/live/invoices.htmland registers the component. - Add a
LiveMountfor it toMountsinsrc/live/mod.rs:LiveMount::identity_boundwhen it belongs to the signed-in user, orLiveMount::public_seedwhen any visitor may use it. Seal it inlive::routes()with.try_live_mount(&mounts.invoices)?, and mount it from the page's controller. - To use another library component in its view, run
suprnova live:add <name>and link the component's stylesheet intemplates/live/layouts/head.html. - Run
suprnova live:checkto prove every view against its component.
Why Suprnova diverges
Laravel's Livewire starter kit renders Blade views with Livewire components, and still builds its assets with Vite. The Live kit has no build step: the framework serves the Live runtime, and the component library ships as files the scaffold installs into your project, which you own and edit like any other view.
Contributing a starter kit
Built something reusable on top of Suprnova and want to upstream it as a canonical kit? See Contributions. We're happy to take a real implementation and round it into a generic kit.
The React, Vue, Svelte and Live scaffolds also ship tests/page_budget.rs. It audits
/, /login, /register, /forgot-password and /reset-password through the
application router and middleware. It creates an isolated test database and
sets the test environment in a child process before runtime threads start.
The Inertia tests audit the router cmd/main.rs serves, Live routes and
RenderCache included, follow built assets when a Vite manifest exists and run
before the frontend build on a fresh scaffold. The Live test boots its
component registry and runtime and audits its served styles and scripts. See Page Budget.
The repository checks the generated tests and origin asset policy in
suprnova-cli/tests/kit_budget.rs; an ignored test there scaffolds each kit
and runs its page budget test. The dogfood application has its own
app/tests/page_budget.rs test over its public entry pages.
Every kit is held to the browser suite in suprnova-cli/tests/kit_browser/.
Run cargo test -p suprnova-cli --test kit_browser -- --ignored --test-threads=1
from the repository root. The harness scaffolds all three kits, builds one
backend against the in-tree framework, builds each frontend, and runs the
same Chromium assertions over each served application. It uses the existing
Playwright browser cache; it does not install browsers. Failed runs print
the kit name, the browser output, the server log, and the retained artifact
directory.
The Live kit is held to suprnova-cli/tests/kit_live.rs and to
live_kit_compiles_and_renders in suprnova-cli/tests/scaffold_snapshot.rs,
which builds a fresh Live scaffold against the in-tree framework, starts it,
and requests its pages:
cargo test -p suprnova-cli --test scaffold_snapshot -- --ignored live_.
Next
Define page subscriptions with Live topic bindings. Register shared topics and model changes with Live.
