Deploy your own

Step by step

What the button actually does

1. Forks the starter template into your own GitHub account.
2. Creates a private Vercel Blob store. Private, not public — file bytes are unreachable without a token even if a URL leaks.
3. Creates an Upstash Redis database through the Vercel Marketplace, billed through your Vercel account. This step asks you to pick a plan, and none of them are free — see what it costs.
4. Injects both sets of credentials as environment variables.
5. Deploys. The index page then runs a real call against all four services and shows you the results, so you get evidence rather than a blank page.

After it lands

The whole backend is one file

// app/api/perusta/[...route]/route.ts
import { perustaFromEnv } from 'perusta-server';
import { toRouteHandlers } from 'perusta-server/next';

export const { GET, POST, OPTIONS } = toRouteHandlers(perustaFromEnv());

Then, from any client component:

import { createClient } from 'perusta';

const cloud = createClient();

await cloud.auth.ensureUser();
await cloud.fs.write('notes/todo.md', '# Hello');

Local development

Run it on your machine

npm install
vercel link                    # connect to the project you deployed
vercel env pull .env.local     # storage credentials + an OIDC token for AI
npm run dev

Cookies are marked Secure everywhere except plain-HTTP localhost, which is detected automatically — so sign-in works locally without you turning anything off.

Read this part

Three honest caveats

Your first deploy answers 401 to everyone

On Pro and Team accounts Vercel switches on Deployment Protection, which puts a login wall in front of the generated *.vercel.app URL. The build succeeds, the dashboard is green, and every perusta call returns:

{"error":{"message":"Protected deployment","code":"401"}}

Nothing is broken. The protection covers the generated URL but not a production custom domain, so either attach a domain, or turn it off under Project → Settings → Deployment Protection. Worth doing before you conclude the deploy failed — and worth knowing if your page is served from another origin, because that fetch gets the 401 too.

SESSION_SECRET is derived unless you set it

Vercel’s Deploy button can prompt for a variable but cannot generate one, so requiring a secret up front would mean opening a terminal before your first deploy finished. When it is unset, perusta derives a session signing key from your Blob token instead.

That means rotating your Blob token signs every user out, and anyone holding that token could forge a session — they would already have full read/write on your storage, so it grants no new reach, but it is one more thing that token can do. For real users, set it:

vercel env add SESSION_SECRET production
# paste the output of: openssl rand -hex 32

AI needs gateway credits

The gateway’s free tier restricts things in two different ways, and it is worth knowing which you have hit.

The Anthropic models are blocked outright — including anthropic/claude-sonnet-5, which is perusta’s own default. That returns forbidden. Other models answer, but a modest number of requests exhausts the free allowance and you start seeing rate_limited.

The template’s demo page pins openai/gpt-4o-mini for exactly this reason, so a fresh deploy shows all four services green. Add credits and drop the model option to get the default back. Storage and auth never touch the gateway and are unaffected.

Money

What it costs

Upstash is not free through the Marketplace. The deploy asks you to pick a plan, and the cheapest is Pay As You Go at $0.20 per 100,000 commands. Everything above it is fixed monthly pricing, starting at $10 for 250 MB. There is no free option in that list, so budget a few cents rather than nothing.

Blob is included in your Vercel plan’s storage allowance, and AI is per token through the gateway. A quiet app costs very little — but “very little” is not “zero”, and it is better to know that before you click than after the first invoice.

There is no perusta pricing, because there is no perusta service. Every resource belongs to you, and removing it is a matter of deleting a Vercel project and its two stores.