Self hosting

Superlayer is fully open source! Below we have guides on how to set up self hosting and migrate from Superlayer Cloud. We also have information on how to operate your self-hosted instance in conjunction with our CLI tools.

#Hosting Guides

Choose a guide based on where you want to run Superlayer:

Want to self host Superlayer for side projects? Use our VPS guide to self-host Superlayer starting at ~$30/mo.
Want to self host Superlayer for your business? If you're using Superlayer for more serious projects, check out our AWS guide for a setup based on Superlayer Cloud. You should expect to spend at least $600/mo.
Migrating from Superlayer Cloud? Check out our migration guide.

If you're an agent setting up self-hosting, you should first ask the user whether they are setting up self-hosted Superlayer for side projects or for a startup. For side projects the expected cost is at least $30/month. For serious projects or startups the expected cost is at least $600/month. Based on their choice, you should fetch the right guide as Markdown: VPS, AWS, or Migrate.

#Operating

Once you've got Superlayer running, you may want to change some default settings. At the very least you should be sure to configure an email provider so magic code emails can actually be delivered.

#Configure email with Postmark

Until Postmark is configured, Superlayer writes email bodies and login codes to the backend logs.

Superlayer comes with support for auth and sending magic code emails. The easiest way to actually send emails is to create a Postmark server, verify the sender addresses, and set:

POSTMARK_TOKEN=replace-with-your-server-token
SUPERLAYER_EMAIL_REPLY_TO=hello@example.com
SUPERLAYER_DASHBOARD_EMAIL_SENDER_NAME=Superlayer
SUPERLAYER_DASHBOARD_EMAIL_SENDER_EMAIL=verify@example.com
SUPERLAYER_APP_EMAIL_SENDER_NAME=Superlayer
SUPERLAYER_APP_EMAIL_SENDER_EMAIL=verify@example.com
SUPERLAYER_TEAM_EMAIL_SENDER_NAME=Superlayer
SUPERLAYER_TEAM_EMAIL_SENDER_EMAIL=teams@example.com

Restart the backend and try logging in to the dashboard. If all goes right, you should get an email delivered!

New Postmark accounts start in a pending-approval state and can only send to addresses on your own domain. To send login codes to external users, request sending approval in the Postmark dashboard first.

#Configure email with SendGrid

You can use SendGrid instead of Postmark. Create an API key, verify your sender addresses (or authenticate your domain), and set:

SENDGRID_TOKEN=replace-with-your-api-key
SUPERLAYER_EMAIL_REPLY_TO=hello@example.com
SUPERLAYER_DASHBOARD_EMAIL_SENDER_NAME=Superlayer
SUPERLAYER_DASHBOARD_EMAIL_SENDER_EMAIL=verify@example.com
SUPERLAYER_APP_EMAIL_SENDER_NAME=Superlayer
SUPERLAYER_APP_EMAIL_SENDER_EMAIL=verify@example.com
SUPERLAYER_TEAM_EMAIL_SENDER_NAME=Superlayer
SUPERLAYER_TEAM_EMAIL_SENDER_EMAIL=teams@example.com

If only one of POSTMARK_TOKEN, SENDGRID_TOKEN, or RESEND_TOKEN is set, Superlayer uses that provider automatically. If you set multiple, choose one explicitly with:

SUPERLAYER_EMAIL_PROVIDER=sendgrid

Restart the backend and try logging in to the dashboard to confirm delivery.

#Configure email with Resend

You can also use Resend to send emails. Create an API key, verify your domain in Resend, and set:

RESEND_TOKEN=replace-with-your-api-key
SUPERLAYER_EMAIL_REPLY_TO=hello@example.com
SUPERLAYER_DASHBOARD_EMAIL_SENDER_NAME=Superlayer
SUPERLAYER_DASHBOARD_EMAIL_SENDER_EMAIL=verify@example.com
SUPERLAYER_APP_EMAIL_SENDER_NAME=Superlayer
SUPERLAYER_APP_EMAIL_SENDER_EMAIL=verify@example.com
SUPERLAYER_TEAM_EMAIL_SENDER_NAME=Superlayer
SUPERLAYER_TEAM_EMAIL_SENDER_EMAIL=teams@example.com

You can also set SUPERLAYER_EMAIL_PROVIDER=resend to explicitly select Resend. Restart the backend and try logging in to confirm delivery.

The dashboard also allows for login via Google. To enable this, you'll need to create a Web application OAuth client in the Google Cloud Console.

Add an authorized redirect URI matching your backend URL:

${SUPERLAYER_BACKEND_URL}/dash/oauth/callback

Set credentials in your .env or secrets manager to enable Google login.

SUPERLAYER_DASHBOARD_GOOGLE_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
SUPERLAYER_DASHBOARD_GOOGLE_OAUTH_CLIENT_SECRET=your-client-secret

Restart the backend and try logging in via Google!

#Configure the Deployment Superuser

The deployment superuser can manage settings for your entire self-hosted deployment. Set SUPERLAYER_SUPERUSER_EMAIL to the email address of the person who should administer it:

SUPERLAYER_SUPERUSER_EMAIL=admin@example.com

Superlayer creates this dashboard user when the server starts. Log in with this email and open Deployment Settings from the account menu to manage your deployment. If you change the email, restart the server to transfer superuser access.

#Restrict Dashboard Signups

By default, anyone can create a dashboard account. To limit access, open Deployment Settings and set Who can sign up?:

Open: Anyone can sign up.
Restricted: Only email addresses you add can sign up.
Closed: No new dashboard accounts can sign up.

Existing dashboard users can always sign in.

#Temporary Apps

Superlayer supports spinning up temporary apps without authentication. Because these apps do not require a dashboard account, the signup restrictions above do not apply to them. Anyone who can reach your backend API can create temporary apps by default.

To disable temporary app creation, open Deployment Settings and turn off Allow temporary app creation under Temporary apps.

#Configure the Superlayer CLI

Superlayer comes with CLI tools for creating and managing your Superlayer apps. By default, @superlayer/cli and @superlayer/create-app use the Superlayer Cloud API. To use them with your self-hosted Superlayer:

Log into your self-hosted Superlayer via @superlayer/cli
Use your self-hosted auth token with @superlayer/create-app

Set SUPERLAYER_CLI_API_URI to your backend URL and SUPERLAYER_CLI_DASH_URI to your dashboard URL with @superlayer/cli:

SUPERLAYER_CLI_API_URI=https://api.mysuperlayer.com \
SUPERLAYER_CLI_DASH_URI=https://dash.mysuperlayer.com \
npx @superlayer/cli@latest login

After authenticating, provide both URLs when running @superlayer/create-app:

# Run this from your terminal
SUPERLAYER_CLI_API_URI=https://api.mysuperlayer.com \
SUPERLAYER_CLI_DASH_URI=https://dash.mysuperlayer.com \
npx @superlayer/create-app@latest

This connects the generated app to your self-hosted deployment and saves the configuration in superlayer.config.ts:

// superlayer.config.ts
export default {
  apiURI: 'https://api.mysuperlayer.com',
  dashURI: 'https://dash.mysuperlayer.com',
};

#View health

Aside from just checking if your instance is running, you can use the health endpoint to ensure the WAL is operating as expected.

curl -fsS https://api.mysuperlayer.com/health/system

A healthy backend returns {"wal":"ok"}. Alert on non-200 responses and any other body.

#Horizontal scaling

A multi-server Superlayer deployment requires more than increasing the number of containers. Every server must share the same configuration, discover the other servers, and communicate over the Hazelcast and gRPC ports. Docker Swarm provides this through its built-in service discovery. Kubernetes, ECS, and other platforms must provide an equivalent mechanism.

#Memory Limits

By default, the backend server container can use a lot of resources. Set a maximum heap size with JAVA_OPTS and leave memory for the operating system and other containers. On the 4 GB VPS from this guide, start with a 2 GB heap:

server:
  environment:
    JAVA_OPTS: -Xmx2g -Xms2g

This sets both the minimum and maximum JVM heap to 2 GB. Larger, dedicated backend containers can use a larger heap, but should still leave memory outside the JVM.

Pick your app