Installation

Get Based running on your VPS in under a minute. You need a server with SSH access and a domain.

Prerequisites

A VPS (any provider — Scaleway, Hetzner, DigitalOcean, etc.) with SSH access and a Debian/Ubuntu base. Based installs Docker and Caddy automatically.

A domain with two DNS A records pointing to your VPS IP. Both are required: Caddy issues certificates on demand, on the first request to a hostname, so DNS has to resolve before a project subdomain can get a certificate.

based.yourdomain.com     → YOUR_VPS_IP
*.based.yourdomain.com   → YOUR_VPS_IP

Install the CLI

One command — requires bun and git:

terminal
curl -fsSL https://based.weirdscience.dev/install.sh | sh

The installer is POSIX sh. Pin a ref instead of main with BASED_REF:

terminal
curl -fsSL https://based.weirdscience.dev/install.sh | BASED_REF=v0.2.0 sh

Or from the repo:

terminal
git clone https://github.com/WeirdScience-dev/based.git
cd based && bun install && bun run setup

Initialize your server

Point Based at your VPS. based init syncs the checkout you run it from, so run it from inside a Based repo — it walks up from the current directory looking for packages/server/package.json and refuses to run if it finds none.

terminal
based init YOUR_VPS_IP --domain based.yourdomain.com

The admin key is generated on the server's .env (mode 0600) and saved to ~/.based/config.json. It is never printed, and you never need to type it again. Re-running init against the same domain reuses the existing key so your other machines keep working — pass --force to rotate it.

Options

terminal
based init <host> --domain <domain>

Options:
  -d, --domain <domain>      Base domain (required)
  -u, --user <user>          SSH user (default: ubuntu)
  -i, --identity <path>      SSH key (default: ~/.ssh/id_ed25519)
  --remote-dir <path>        Install directory (default: /var/www/based)
  --dry-run                  Print the .env and Caddyfile it would write, then stop
  --force                    Rotate the admin key even if this domain is installed

--dry-run touches nothing on the server. It is the quickest way to see the exact /etc/caddy/Caddyfile Based would install, which is also the starting point for a manual setup.

What happens during init

The CLI connects via SSH and:

  1. Installs Docker and Caddy if they are not present
  2. Creates /srv/based/projects and /srv/based/backups
  3. Syncs the Based checkout via rsync
  4. Writes .env with a random admin key, mode 0600
  5. Runs docker compose build then up -d --wait, so it blocks until the healthcheck passes
  6. Writes /etc/caddy/Caddyfile, validates it, and reloads Caddy
  7. Saves the config to ~/.based/config.json

The base domain serves the static site and proxies only /admin/* and /health to the server. Project subdomains are proxied wholesale, with certificates issued on demand — Caddy asks the server whether the hostname is a real project before requesting one, so a stranger pointing DNS at your box cannot make you issue certificates.