---
title: "Architecture"
description: "The services behind wervt and how apps are isolated."
canonical_url: "https://docs.lightdrop.cloud/self-hosting/architecture"
---
# Architecture

> The services behind wervt and how apps are isolated.

<architecture-diagram>



</architecture-diagram>

<table>
<thead>
  <tr>
    <th>
      Service
    </th>
    
    <th>
      Image
    </th>
    
    <th>
      Role
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Runtime
    </td>
    
    <td>
      <code>
        ghcr.io/supabase/edge-runtime
      </code>
    </td>
    
    <td>
      Main worker plus one isolate per active app
    </td>
  </tr>
  
  <tr>
    <td>
      Postgres
    </td>
    
    <td>
      <code>
        pgvector/pgvector
      </code>
      
       (Postgres 18, <code>
        wal_level=logical
      </code>
      
      )
    </td>
    
    <td>
      One database <code>
        wervt
      </code>
      
      , one schema and role per app
    </td>
  </tr>
  
  <tr>
    <td>
      PgBouncer
    </td>
    
    <td>
      <code>
        edoburu/pgbouncer
      </code>
    </td>
    
    <td>
      Pools the isolates' connections, a pool per app role
    </td>
  </tr>
  
  <tr>
    <td>
      Electric
    </td>
    
    <td>
      <code>
        electricsql/electric
      </code>
    </td>
    
    <td>
      Streams table changes to shapes
    </td>
  </tr>
  
  <tr>
    <td>
      Logs
    </td>
    
    <td>
      <code>
        victoriametrics/victoria-logs
      </code>
    </td>
    
    <td>
      App and runtime logs, 14 days
    </td>
  </tr>
  
  <tr>
    <td>
      Storage
    </td>
    
    <td>
      <code>
        dxflrs/garage
      </code>
    </td>
    
    <td>
      S3 object storage, one bucket and key per app
    </td>
  </tr>
  
  <tr>
    <td>
      Images
    </td>
    
    <td>
      <code>
        imgproxy/imgproxy
      </code>
    </td>
    
    <td>
      Resizes images of the apps' files (<code>
        imageUrl()
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      Docker proxy
    </td>
    
    <td>
      <code>
        wollomatic/socket-proxy
      </code>
    </td>
    
    <td>
      Read-only Docker API for the dashboard's System page
    </td>
  </tr>
</tbody>
</table>

The dashboard's **System** page (admins only) lists the stack's containers with their state,
image, CPU, memory and last log lines. Control reads them through the Docker proxy, which only
answers control and only allows listing containers and reading their stats and logs: not
inspecting them (that shows their environment), and nothing that changes anything. The proxy is
on its own network, which the runtime and with it app code isn't on.

## Main worker

`runtime/main` is the only long-running code. For each request it:

1. reads the app name from the first label of the host (`todos.lightdrop.cloud` → `todos`),
2. serves the file from `apps/<name>/public` if one matches, with immutable caching for `/_nuxt/`,
3. otherwise reads `apps/<name>/wervt.json` and hands the request to the app's isolate
(`EdgeRuntime.userWorkers.create`), passing the app's environment.

An app is a directory with the Nitro `deno-server` output:

```bash
apps/todos/
├── server/      # .output/server, entry index.mjs
├── public/      # .output/public
└── wervt.json   # { "database": true }
```

## Isolate limits

<table>
<thead>
  <tr>
    <th>
      
    </th>
    
    <th>
      
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Memory
    </td>
    
    <td>
      150 MB
    </td>
  </tr>
  
  <tr>
    <td>
      CPU per request
    </td>
    
    <td>
      10 s soft, 20 s hard
    </td>
  </tr>
  
  <tr>
    <td>
      Idle timeout
    </td>
    
    <td>
      5 minutes
    </td>
  </tr>
</tbody>
</table>

## Environment

Every app receives `WERVT_APP_URL` (where it's served, `https://<app>.<WERVT_BASE_DOMAIN>`, or the
runtime's own `WERVT_APP_URL` with `{app}` replaced), `WERVT_AUTH_URL` (the login) and
`WERVT_RUNTIME_URL`. `@wervt/nuxt` builds an app's MCP endpoint and its OAuth issuer from the first
two (see [App MCP](https://docs.lightdrop.cloud/guides/mcp)).

Every app also receives `WERVT_APP` and `WERVT_TOKEN`, its identity for runtime services
(Electric, mail). Apps with a database get `DATABASE_URL` for their own role, pointing at
PgBouncer (see below). Role passwords and app tokens are HMACs of the app name with
`WERVT_DB_SECRET`, so the runtime and the deploy tooling derive the same values without storing
them.

The runtime answers these services (`/_wervt/electric/v1/shape`, `/_wervt/mail`,
`/_wervt/access`, `/_wervt/identity-token`) only on its own address (`WERVT_RUNTIME_URL`), never
on an app's public hostname, so an app token that leaks can't be used from the internet. The
control plane calls the runtime for tasks and boot checks with a credential of its own, which no
app holds.

With storage configured, every app also receives `WERVT_S3_URL`, `WERVT_S3_PUBLIC_URL`,
`WERVT_S3_BUCKET` and its own `WERVT_S3_ACCESS_KEY_ID` / `WERVT_S3_SECRET_ACCESS_KEY`, derived the same
way. Garage itself enforces that a key only works on its app's bucket. The control plane gets
`WERVT_S3_PUBLIC_URL` too: the dashboard's file browser downloads through links it presigns for
that URL, so files never pass through the dashboard.

With imgproxy next to Garage (`WERVT_IMGPROXY_URL` on the runtime), apps also get
`WERVT_IMAGE_KEY` and the runtime serves `/_wervt/image/…` on every app's host: it checks the
URL's signature, presigns a link to the app's own bucket and passes it to imgproxy. imgproxy has
no credentials, takes requests only from inside the stack and fetches only from Garage
(`IMGPROXY_ALLOWED_SOURCES`), so an isolate calling it directly gets nothing its own bucket
doesn't hold. It caches nothing; with Cloudflare in front, a public app's images are cached there.

## Connection pooling

Isolates connect to PgBouncer, not to Postgres: every isolate holds its own connections, and many
apps with parallel isolates would exhaust `max_connections`. PgBouncer runs in transaction mode
with a pool per app role, so each app keeps its own `search_path` and at most a few server
connections (`MAX_DB_CONNECTIONS` caps the total). It checks app passwords with `auth_query`
through `pgbouncer.get_auth()`, which control creates on startup and which returns the hashes of
`app_*` roles only. Control (migrations, analytics, mail) and Electric connect to Postgres directly.

Each app role has a `statement_timeout` and an `idle_in_transaction_session_timeout`
(`WERVT_STATEMENT_TIMEOUT`, 30 s, and `WERVT_IDLE_IN_TRANSACTION_TIMEOUT`, 60 s), set on every
provisioning and on control's start, so a hanging query or a transaction left open by a crashed
isolate can't hold connections and locks of the shared server. Migrations switch them off for
their session.

## Requests between apps

An isolate that calls another app on the same runtime (an app fetching the login's signing keys,
the login checking an app's MCP metadata) sends the request to `WERVT_RUNTIME_URL` with the app's
host in `x-wervt-host`. The main worker honors that header only on requests to its own address and
routes them like any other request, private-app checks included. This avoids a round trip through
the internet, and the local stack's `*.localhost` names don't resolve inside the runtime at all.

## Electric gateway

Apps never get Electric's secret. A shape route calls the runtime at `/_wervt/electric/v1/shape`
with its app token. The gateway:

- checks the token against the app name,
- only accepts an unqualified table name and pins it to `app_<name>.<table>`,
- forwards `where`, `params`, `columns` and Electric's protocol parameters,
- adds the Electric secret and streams the response back.

An app can therefore only ever stream its own tables, whatever its code does.

## Logs

The runtime also starts an event worker (`runtime/events`), which receives every isolate's console
output and lifecycle events (boot, boot failure, uncaught exception, shutdown). It takes the app and
release from the isolate's path, so an app can't log under another's name, parses JSON lines into
fields, and sends batches to VictoriaLogs with one stream per app. VictoriaLogs has no auth and is
only reachable inside the stack; the control plane reads it and restricts every query to one app with
an extra stream filter, which holds for `OR`, subqueries and `union` too.

The event worker only sees isolates. The main worker sends its own logs the same way: errors about
one app (an isolate that failed to start for a request, a failed task call or boot check) go to that
app's stream as `type:=Runtime`, everything else it prints to `_runtime` as `type:=Main`, which only
admins can read (**Logs** → **Runtime** in the dashboard).

Saved queries live in `<apps>/.logs/<app>.json` (`_all.json` for queries across apps). The control
plane checks their alerts every minute with a `stats count()` query, sends the mails through the
platform's mail (Brevo or the mail server, logged under `_alerts` in the mail status) and keeps each
alert's state in the same file. Checks missed while it's down aren't caught up.


## Sitemap

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