vm-atlogin-mas-matrix
atlogin + MatrixAuthentificationService + Matrix
Star
Fork
Watch
1 1 0
Files
hosts
modules
packages
.gitignore
flake.lock
flake.nix
README.md
README.md

Matrix Synapse + Element Web + ATLogin #

A NixOS infrastructure for Matrix with Bluesky/ATProto authentication via ATLogin.

Warning: The VM uses hardcoded dummy secrets for local testing only. Do not use these values in production.

VM Test Environment #

Quick Start #

Without tunnel (localhost only - won't work with external PDS):

nix run .#vm

With Tailscale (recommended - works with Element X on phone):

TAILSCALE_HOSTNAME=matrix-test.tail1234.ts.net \
TAILSCALE_AUTHKEY=tskey-auth-xxx \
nix run --impure .#vm

Then:

With ngrok (alternative):

# Terminal 1: Start ngrok
ngrok http 9411

# Terminal 2: Start the VM with the ngrok URL
ATLOGIN_URL=https://abc123.ngrok-free.app nix run --impure .#vm

Then open http://localhost:8080 in your browser.

Services #

Service URL Description
Element Web http://localhost:8080 Matrix web client
Synapse API http://localhost:8008 Matrix homeserver
ATLogin http://localhost:9411 ATProto OIDC provider

Why is a tunnel needed? #

ATProto OAuth uses Pushed Authorization Requests (PAR). When you authenticate:

  1. You click "Sign in with Bluesky" in Element
  2. ATLogin starts an OAuth flow with your PDS (e.g., bsky.social)
  3. Your PDS needs to fetch ATLogin's client-metadata.json to validate the client
  4. If ATLogin is on localhost, the PDS can't reach it

Tailscale (with HTTPS enabled) or ngrok provides a URL that the PDS can reach.

Tailscale Funnel exposes the VM publicly with HTTPS. Benefits over ngrok:

  • Stable URL (doesn't change on restart)
  • HTTPS with auto-generated certificates
  • Access from any device

1. Enable HTTPS in Tailscale Admin #

  1. Go to Tailscale Admin Console
  2. Enable "HTTPS Certificates" for your tailnet

2. Get an Auth Key #

  1. Go to Tailscale Keys
  2. Generate a new auth key (reusable + ephemeral recommended for test VMs)
  3. Copy the key (starts with tskey-auth-)

3. Find Your Hostname #

Your hostname will be: <machine-name>.<tailnet-name>.ts.net

For example: matrix-test.tail1234.ts.net

4. Start the VM #

TAILSCALE_HOSTNAME=matrix-test.tail1234.ts.net \
TAILSCALE_AUTHKEY=tskey-auth-xxx \
nix run --impure .#vm

The VM will:

  • Auto-join your tailnet on boot
  • Generate HTTPS certificate via tailscale cert
  • Set all URLs to use your Tailscale hostname

5. Test with Element X #

On your phone:

  1. Install Element X
  2. Enter homeserver: https://matrix-test.tail1234.ts.net
  3. Sign in with Bluesky

Step-by-Step with ngrok #

1. Install ngrok #

# macOS
brew install ngrok

# Or download from https://ngrok.com/download

2. Start ngrok #

ngrok http 9411

You'll see output like:

Forwarding    https://abc123.ngrok-free.app -> http://localhost:9411

Copy that https://...ngrok-free.app URL.

3. Start the VM #

ATLOGIN_URL=https://abc123.ngrok-free.app nix run .#vm

The VM will automatically configure ATLogin and Synapse to use this public URL.

4. Test #

  1. Open http://localhost:8080
  2. Click "Sign in with Bluesky"
  3. Enter your Bluesky handle (e.g., alice.bsky.social)
  4. Authenticate with your Bluesky account
  5. You're logged into Matrix!

VM Controls #

  • Quit VM: Press Ctrl+A X
  • Console: Auto-logs in as root
  • Logs: journalctl -u atlogin -f or journalctl -u matrix-synapse -f

Ports #

The VM forwards these ports to your host:

  • 8080 → 80 (nginx/Element Web)
  • 8008 → 8008 (Synapse)
  • 9411 → 9411 (ATLogin)