Skip to main content
Overlay is open source (AGPL-3.0-only) and runs on your own infrastructure. Source: github.com/LayerNorm/overlay-web.

​
What you run

There is no separate worker or queue to run: background work runs inside the Convex backend.

​
Deployment models

Every self-hosted or managed deployment serves one customer. Departments, classes and teams are workspaces and roles inside it, not separate tenants. See Tenancy.

​
Requirements

  • A Linux host or container platform that runs Docker images.
  • For a pilot: one 2-vCPU host with 8 GB of memory (such as an EC2 t3.large) and at least 20 GB of disk runs the app and the Convex backend together. Building from source needs 4 vCPU and 40 GB.
  • For production: managed Postgres for Convex persistence, S3-compatible storage, Redis, and TLS in front of both the app and the Convex backend.
  • An identity provider if you want SSO, and at least one model provider key if you want AI features.
  • Node.js 22 or newer on the operator machine, to deploy the Convex functions.

​
Install

One-command install

The fastest pilot: one script sets up the app with overlayctl.

Docker on one host

App, Convex and Redis on a single EC2 instance with RDS.

AWS reference

ECS, RDS, ElastiCache and S3 for production.

From source

Keep the source checkout for audits and customization.
Every path needs the Convex backend. To run the web app with plain Node.js instead of Docker, see Node.js without Docker.

​
Configure

Configuration comes from three layers, highest first: environment variables, overlay.config.json (OVERLAY_CONFIG_FILE), then built-in defaults. Keep secrets in environment variables and the deployment’s shape (providers, features, compliance) in the JSON file.
  • Runtime config: the JSON file, presets and validated example profiles.
  • Environment variables: every variable and which side (app or Convex) it belongs on.
  • Providers: what each provider family does and what is supported.

​
Operate

​
Licensing

First-party code is AGPL-3.0-only; submodules and third-party code keep their own licenses. If you modify Overlay and offer it to others over a network, you must offer them your source, and a modified distribution needs its own branding unless LayerNorm gives written permission. See License and Self-hosting obligations.