---
title: "Private apps"
description: "Put a login in front of an app and decide who gets in."
canonical_url: "https://docs.lightdrop.cloud/guides/private-apps"
---
# Private apps

> Put a login in front of an app and decide who gets in.

Apps are **private by default**. Before anything of a private app is served, the runtime checks
that the visitor is signed in and on the app's list. Nothing runs in the app's isolate for anyone
else.

```bash
wervt access my-app                                   # show visibility and list
wervt access my-app --add friend@example.com,*@company.com
wervt access my-app --remove friend@example.com
wervt access my-app --public                          # anyone, no login
wervt access my-app --private
wervt access my-app --invite                          # private, people with access invite others
wervt access my-app --index                           # public and listed in search engines
```

Admins (`WERVT_ADMIN_EMAILS` on the runtime) can open every private app. The app's owner and
members always get in, without being on the list.

## Search engines

Public apps are kept out of search engines too, until you say otherwise. Every response of an app
carries `X-Robots-Tag: noindex`, pages and files alike, so Google & co. drop it from their results
even when someone links to it. For a site people should find, turn that off:

```bash
wervt access my-app --index      # back with --no-index
```

The dashboard has the same switch under **Access**, shown while the app is public.

- It only counts while the app is public. Private and invite-only apps stay out either way; the
setting comes back with `--public`.
- With `--index` the runtime adds nothing, so the app's own `noindex` (a header or
`<meta name="robots">`) still keeps single pages out. Without it, an app's own `noindex` stays as
it is, with whatever it adds (`nofollow`, …).
- Previews (`my-app--pr-1`) never get it: they'd compete with the app in search results.
- `robots.txt` is the app's own. The header doesn't need one, and blocking a path there would hide
the `noindex` from crawlers.

## Invite-only apps

For apps whose users should bring in others themselves (a league, a shared board, a game room),
make the app invite-only. The runtime still checks the login and the list before anything of the
app runs, as for a private app, but the app may add people to the list:

```bash
wervt access my-app --invite
```

```ts [server/api/invites.post.ts]
import { useValidatedBody, useWervtAccess } from '@wervt/nuxt/server'
import { defineEventHandler } from 'nuxt/server'
import * as v from 'valibot'

export default defineEventHandler(async (event) => {
  const { email } = await useValidatedBody(event, { email: v.pipe(v.string(), v.email()) })
  return useWervtAccess(event).invite(email)
})
```

`useWervtAccess(event)` acts as the signed-in user of the request: `invite(email)`, `revoke(email)`
and `list()` (who was invited, by whom and when). The runtime vouches for that user, so an app
can't invite on behalf of someone else, and only someone with access can invite. Everyone with
access may invite; if only some of your users should, check that in the route.

When getting in shouldn't mean letting others in, leave inviting to the app's owner, members and
admins. The control plane enforces it, whatever the app's routes do; `list()` and `revoke()`
follow the same rule:

```bash
wervt access my-app --invite --invite-by owners   # back with --invite-by anyone
```

To mail the invited person, send `InviteEmail` from `@wervt/nuxt/email` (see [Email](https://docs.lightdrop.cloud/guides/email)):

```ts
const { invited } = await useWervtAccess(event).invite(email)
if (invited)
  await sendMail({
    to: email,
    template: InviteEmail,
    props: { by: user.name ?? user.email, app: 'Dartsen', url: 'https://dartsen.lightdrop.cloud' },
  })
```

- Invites are real addresses, no `*@domain`. Each person can invite 25 people a day, an app can
have 500 invited people.
- `revoke()` only takes back invites. The list you manage with `wervt access --add` stays yours.
- Invited people show up in `wervt access my-app` and the dashboard with who invited them. Remove
them there with `--remove` like anyone else.
- Invites count only while the app is invite-only: `--private` shuts invited people out, `--invite`
lets them back in.
- In `nuxt dev`, invites are kept in memory and nobody is actually let in.

## Owners and members

With `WERVT_ADMIN_EMAILS` set on the control plane, everyone else who signs in with `wervt login`
manages only their own apps. The first deploy of a free name makes them its owner; names of other
people's apps are taken, and their apps don't show up at all.

```bash
wervt members my-app                                  # show owner and members
wervt members my-app --add friend@example.com         # members can deploy and manage the app
wervt members my-app --remove friend@example.com
wervt members my-app --owner friend@example.com       # hand it over, you stay a member
```

Only the owner can delete the app or change its members. Admins manage every app; apps deployed
before ownership existed belong to them until an admin names an owner with `--owner`.

### Limits

Each account may own a limited number of apps (memberships don't count), and those apps may take a
limited amount of space:

<table>
<thead>
  <tr>
    <th>
      Limit
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      What happens past it
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Apps
    </td>
    
    <td>
      3
    </td>
    
    <td>
      Deploying a new name is refused, with the apps the account already owns
    </td>
  </tr>
  
  <tr>
    <td>
      Database
    </td>
    
    <td>
      1 GB per app
    </td>
    
    <td>
      Deploys warn from 80 %; past the limit they're refused until the app deletes data
    </td>
  </tr>
  
  <tr>
    <td>
      Files
    </td>
    
    <td>
      5 GB per app
    </td>
    
    <td>
      The bucket is full: uploads fail with <code>
        403 AccessDenied
      </code>
      
       (a Garage quota)
    </td>
  </tr>
  
  <tr>
    <td>
      Releases
    </td>
    
    <td>
      1 GB for all apps
    </td>
    
    <td>
      Older releases are pruned first; a release that doesn't fit next to the active one is refused
    </td>
  </tr>
  
  <tr>
    <td>
      Services
    </td>
    
    <td>
      Off
    </td>
    
    <td>
      Memory the <a href="https://docs.lightdrop.cloud/guides/services">
        service containers
      </a>
      
       of all apps may ask for together; a deploy past it is refused
    </td>
  </tr>
  
  <tr>
    <td>
      Images
    </td>
    
    <td>
      10 GB for all apps
    </td>
    
    <td>
      Space the images of all services and their previews may take; a build or pull past it fails and its image is removed
    </td>
  </tr>
</tbody>
</table>

Images count each layer once, at its unpacked size: services built on the same base image share it.
The images of the releases kept for rollbacks count too, until those releases are pruned.

The defaults come from the control plane: `WERVT_DEFAULT_APP_LIMIT` (`none` for no limit) and
`WERVT_DEFAULT_DATABASE_LIMIT`, `WERVT_DEFAULT_STORAGE_LIMIT`, `WERVT_DEFAULT_RELEASES_LIMIT`,
`WERVT_DEFAULT_SERVICES_LIMIT`, `WERVT_DEFAULT_IMAGES_LIMIT` (sizes like `500MB` or `2GB`, `none`
for no limit, `0` for services off). Admins give accounts their own limits in the
dashboard's **Accounts** page, or with the CLI:

```bash
wervt accounts                          # every account, its apps and limits
wervt accounts friend@example.com --apps 10
wervt accounts friend@example.com --apps none      # no limit
wervt accounts friend@example.com --apps default   # back to the server's default
wervt accounts friend@example.com --database 2GB --storage 20GB --releases 2GB
wervt accounts friend@example.com --services 4GB  # service containers, 0 turns them off
wervt accounts friend@example.com --images 20GB   # space for their service images
wervt accounts friend@example.com --admin          # make them an admin
wervt accounts friend@example.com --revoke-admin   # and take it away, right away
```

Only admins from `WERVT_ADMIN_EMAILS` can appoint admins. Appointed admins manage every user's apps
and accounts, but the platform's own apps (auth, dashboard and the other reserved names) stay with
the env's admins: appointed ones can read their info and logs, not deploy to them, see their env or
touch their database. They also can't approve a `wervt login` for someone else or merge an account
into an admin.

An app is held to its owner's limits; apps of admins and apps without an owner have none. Lowering
a limit keeps existing apps running: it only stops new apps, the next deploys or new uploads.

Every app's database role also has a `statement_timeout` (30 s) and an
`idle_in_transaction_session_timeout` (60 s), so one app's runaway query can't hold the shared
Postgres. Migrations run without them. Self-hosters change them with `WERVT_STATEMENT_TIMEOUT` and
`WERVT_IDLE_IN_TRANSACTION_TIMEOUT`.

## How it works

1. A visitor without a session is redirected to `auth.lightdrop.cloud` (page visits through a
[link preview](#link-previews) page), which offers Google, GitHub, Discord,
Twitch, Spotify, passkeys and email: a code by mail, or a password once one is set (powered by
[better-auth](https://better-auth.com)).
2. After login the auth app sets a short-lived signed `wervt_session` cookie on `.lightdrop.cloud`, so one
login covers every private app. Only for a confirmed address: a provider that doesn't vouch for
it (Spotify) leads to a code to that address first, so an address on an app's list lets in only
whoever reads its mail. MCP clients wait for the same code before they get a token.
3. The runtime verifies that cookie locally (HMAC, no network call), checks the list and forwards the
request. It strips the cookie first, so app code can never read or replay it.
4. Signed in but not on the list? The visitor sees a "No access" page in the app's
[look](https://docs.lightdrop.cloud/api/module#login-branding) and language (English or German). It names the address they signed in
with, tells them to ask whoever sent the link, and offers to sign in with another account.

Access is managed by the control plane, not by app code: an agent editing an app can't make it
public.

A CDN in front of wervt (Cloudflare, say) can't tell who is signed in, so it must not keep a
private app's files. The runtime marks every response of an app that isn't public `private`,
build assets included: browsers still keep them, CDNs don't. Files a CDN kept while the app was
public stay there, though. After making a public app private, purge its host from the CDN's
cache.

MCP clients and native apps send an access token instead of the cookie (see
[Native apps](https://docs.lightdrop.cloud/guides/native-apps)). The runtime verifies it on every path and checks the same
list before the app is reached. A missing or invalid token gets a 401 instead of the login redirect.

## Testing a private app

`curl` and headless browsers have no login, so a private app answers them with the login redirect.
`wervt token` mints a short-lived access token for your own account on one app, so you (or your
agent) can check protected routes and pages right after a deploy:

```bash
TOKEN=$(wervt token my-app)                # 15 minutes; --ttl 1h at most
curl -H "Authorization: Bearer $TOKEN" https://my-app.lightdrop.cloud/api/me
```

The app sees you, like after a browser login: `useWervtUser(event)` returns your account with its
id, name and linked logins.

For a headless browser, `--cookie` prints the token as a cookie for the app's host, ready for
Playwright:

```bash
wervt token my-app --cookie > cookie.json
```

```ts
import { readFileSync } from 'node:fs'

await context.addCookies([JSON.parse(readFileSync('cookie.json', 'utf8'))])
await page.goto('https://my-app.lightdrop.cloud/')
```

- Only the app's owner, its members and admins get a token, and only for their own account:
there's no way to act as someone else. Deploy and read tokens can't mint one; sign in with
`wervt login`.
- A token works on that one app only and for at most an hour. It passes the same list as a login,
so someone removed from the app can't use theirs anymore.
- Your account must have signed in to wervt in a browser once.
- Every token is logged in the app's logs (`wervt logs my-app 'type:=AgentToken'`, with who asked
for it), and requests made with one carry `agentToken` in their wide event, with the same id:
`wervt logs my-app 'agentToken.id:*'`.
- The cookie (`wervt_agent`) is host-only: other apps never receive it. It is a cookie rather than a
one-time login link, so no credential ends up in URLs and browser history.

## Link previews

Shared links of a private app are fetched without a login (iMessage, Slack, WhatsApp, Discord, …).
Instead of redirecting such a visit straight to the login, the runtime answers page visits with a
small page carrying the app's preview tags (`og:title`, `og:image`, icon, …), which sends people on
to the login right away. Crawlers read the tags; people don't notice the detour. API calls, `/mcp`
and form posts still get the plain redirect or 401.

By default the preview only shows the app's name and icon (`<link rel="icon">` in `app.head`, or
`favicon.png`/`.svg`/`.ico` in `public/`): for some private apps the title alone says too much.
Opt in to more in `nuxt.config.ts`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@wervt/nuxt'],
  wervt: {
    // true: title, description, og:image and theme-color from app.head
    preview: {
      title: 'Scoreboard',
      description: 'Scores with friends',
      image: '/og.png', // public/og.png, 1200×630
      icon: '/favicon.png',
      themeColor: '#0a0a0b',
    },
  },
})
```

Fields you leave out fall back to `app.head`. `image` and `icon` are files in `public/` (or https
URLs). Only these two are served without a login, at `/_wervt/preview/image` and
`/_wervt/preview/icon`; `/og.png` itself stays private. `preview: false` turns the page off, so
visitors without a login get the plain redirect again.

The preview is written into the build (`server/wervt-preview.json`), so the app's isolate doesn't
start for these visits. A change takes effect with the next deploy.

## The user in your app

Private apps always receive the signed-in user. Public apps receive one when the visitor is signed
in, so a public app can still have optional accounts, admins or "Twitch users only" features.

<code-group>

```ts [server/api/me.get.ts]
import { useWervtUser } from '@wervt/nuxt/server'
import { defineEventHandler } from 'nuxt/server'

export default defineEventHandler((event) => useWervtUser(event))
// { id, email, name?, image?, accounts?: { github?: '…', twitch?: '…' }, role }
```

```vue [app.vue]
<script setup lang="ts">
const user = useWervtUser() // auto-imported, ready before the first render
</script>

<template>
  <p v-if="user">Hi {{ user.name ?? user.email }}</p>
</template>
```

</code-group>

During SSR the user travels in the payload. Apps without SSR (`ssr: false`) load it from
`/_wervt/user` before the app renders, so `useWervtUser()` is set either way.

Use `user.id` to scope data, e.g. `proxyShape(event, { table: notes, where: '"ownerId" = $1', params: [user.id] })`.
People can change their address on their account page, and the id stays the same. Their apps,
memberships, list entries and invites move to the new address, but `*@domain` entries don't, since
they're about the domain.

`image` is the picture people upload on their account page, or the one from GitHub & co. when they
signed up there. It's a public URL, and a new picture gets a new URL, so it can be cached for good.
Like the name, apps see a change right away in the browser it was made in, and elsewhere once the
session renews (within 12 hours).

`accounts` maps each login provider the user linked to their id there, e.g. check
`user.accounts?.twitch` before letting someone into a Twitch-only feature.

`emailVerified` is `true` when the address was confirmed, by a code or by a login provider that
vouches for it. The login confirms every address before an app sees the visitor, so it's missing
only with the local dev login and on sessions issued before that rule, which expire within 12 hours.
Requests with a token (MCP clients, native apps, `wervt token`) don't carry it.

### Roles and admin features

`role` says what the user is to this app, from the same rules the runtime lets them in by:

<table>
<thead>
  <tr>
    <th>
      Role
    </th>
    
    <th>
      Who
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        owner
      </code>
    </td>
    
    <td>
      The app's owner (<code>
        wervt members
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        member
      </code>
    </td>
    
    <td>
      One of its members
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        admin
      </code>
    </td>
    
    <td>
      A wervt admin (<code>
        WERVT_ADMIN_EMAILS
      </code>
      
      ) who is neither
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        invited
      </code>
    </td>
    
    <td>
      Invited through the app (invite-only apps, see <a href="#invite-only-apps">
        above
      </a>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        allowed
      </code>
    </td>
    
    <td>
      On the app's list (<code>
        wervt access --add
      </code>
      
      , <code>
        *@domain
      </code>
      
       included)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        public
      </code>
    </td>
    
    <td>
      Anyone else signed in to a public app
    </td>
  </tr>
</tbody>
</table>

The first that fits wins: an admin who owns the app is its `owner`. Build the app's own admin
features (fixing someone's entry, taking back invites) on owners and members rather than a list
of emails in an environment variable, so `wervt members` decides who runs the app:

```ts [server/api/invites/[email].delete.ts]
import { requireWervtRole, useValidatedParams, useWervtAccess } from '@wervt/nuxt/server'
import { defineEventHandler } from 'nuxt/server'
import * as v from 'valibot'

export default defineEventHandler(async (event) => {
  requireWervtRole(event, 'owner', 'member', 'admin')
  const { email } = await useValidatedParams(event, { email: v.pipe(v.string(), v.email()) })
  return useWervtAccess(event).revoke(email)
})
```

`requireWervtRole(event, ...roles)` returns the user, or throws 401 without one and 403 with
another role. In the app, `useWervtUser().value?.role` shows or hides the matching buttons; the
route still decides. Users of the app's own `/mcp` tokens (`wervt:mcp:token`) have no role unless
the hook sets one.

### Sign in and out from an app

Every app host has `/_wervt/login` and `/_wervt/logout`. Link to them with a full page load (not a
client-side navigation); `redirect` is a path in your app to come back to:

```vue
<UButton label="Sign in" :to="wervtLoginUrl(route.fullPath)" external />
<UButton label="Sign out" :to="wervtLogoutUrl('/')" external />
```

`wervtLoginUrl` and `wervtLogoutUrl` are auto-imported. Signing out signs out of all wervt apps.

### The account page

People change their name, picture and email on wervt's account page. `/_wervt/account` opens it
in your app's look ([`wervt.brand`](https://docs.lightdrop.cloud/api/module#login-branding)), with a button back to `redirect`:

```vue
<UButton label="Account" :to="wervtAccountUrl(route.fullPath)" external />
```

The way back renews the session, so your app shows the changes right away, on a custom domain
too. There's no API for apps to change these themselves: a code to a new address would go wherever
the app says, so any app could take over its visitors' accounts. Keep data only your app needs,
like a bio or a display name of its own, in your tables under `user.id`. In `nuxt dev` the link
shows a note instead, since wervt's login doesn't run there.

In `nuxt dev` there's no wervt login: `/_wervt/login` signs you in as a dev user
(`dev@wervt.localhost`, with a Twitch account linked, as the app's `owner`). Change it with the
module option `wervt: { dev: { user: { … } } }`, e.g. `role: 'public'` to see the app as a
visitor.

To try roles and flows with more than one user, sign in as someone else for a while:
`/_wervt/login?as=<name or email>&role=<role>`. `as` picks the user (`alice` is
`alice@wervt.localhost`, id `dev-alice`; the same `as` is always the same user), `role` is one of
`owner`, `member`, `admin`, `invited`, `allowed` and `public`, and either works alone: without `as`
you stay the dev user with another role, without `role` the persona has the dev user's. Plain
`/_wervt/login` is the dev user again. Each browser keeps its own login, so two windows (or two
Playwright contexts) can be two users at once:

```text
http://localhost:3000/_wervt/login?as=alice&role=member&redirect=/rooms/1
http://localhost:3000/_wervt/login?as=bob&role=invited&redirect=/rooms/1
```

Personas only exist in `nuxt dev` on your machine. A Studio preview signs in only the person
building the app, as themselves, and a deployed app never sees the dev login at all.

## Sessions for your own data

For state of your own (which room a browser joined, a cart, anonymous visitors), use the session
from `nuxt/server`. wervt gives every app its own `NUXT_APP_SECRET`, which Nuxt derives the session
key from, so there's nothing to configure:

```ts
import { useSession } from 'nuxt/server'

const session = await useSession<{ rooms?: string[] }>(event, { name: 'my-app' })
await session.update({ rooms: [...(session.data.rooms ?? []), roomId] })
```

## Secrets for apps

`wervt env` sets environment variables for an app. Values are write-only: reading lists only the keys.

```bash
wervt env my-app --set NUXT_API_KEY=… --set NUXT_OTHER=…
wervt env my-app --unset NUXT_OTHER
```

The app reads them through `runtimeConfig`: `NUXT_API_KEY` sets `runtimeConfig.apiKey` (see
[Configuration and secrets](https://docs.lightdrop.cloud/guides/configuration)). Names starting with `WERVT_` and `DATABASE_URL`
are reserved for the runtime. Changes apply from the next request, which starts a fresh isolate; no
redeploy needed. Access changes apply immediately too.


## Sitemap

See the full [sitemap](https://docs.lightdrop.cloud/sitemap.md) for all pages.
