Self-host

Self-host Matrix OS when you want the cloud-coding computer on infrastructure you control. The installer uses the same published host bundle shape as Matrix Cloud, then configures a standalone profile with local Postgres, systemd services, nginx, the web shell, gateway, code-server, and optional coding-agent tools.

curl -fsSL https://matrix-os.com/install-server.sh | sudo bash

Preview self-host path

The self-host installer is for developers comfortable operating a VPS. Matrix Cloud still provides managed routing, Clerk auth, backups, updates, billing, and integrations. Self-host installs start with nginx Basic Auth and can work from the server IP address; put the host behind HTTPS, Tailscale, Cloudflare Access, or another trusted edge for long-term use.

Requirements

A fresh apt-based Linux VPS with systemd.
Root or sudo access.
Ports 80 and the internal loopback service ports available.
Enough disk for the Matrix host bundle, local Postgres, projects, and coding tools.
Optional DNS record pointing at the server before install. If you skip DNS, the installer uses the server IP/default nginx vhost.

Install

Create or choose a VPS

Start from a clean Ubuntu or Debian-style server. A small development host works for evaluation; use more CPU and memory if you plan to run multiple coding agents and dev servers.

Run the main-domain installer

curl -fsSL https://matrix-os.com/install-server.sh | sudo bash

No domain is required. The default MATRIX_DOMAIN=_ makes nginx answer on the server IP address and the installer prints an http://<server-ip> URL.

Optional configuration:

curl -fsSL https://matrix-os.com/install-server.sh | sudo \
  MATRIX_DOMAIN=matrix.example.com \
  MATRIX_INSTALL_HANDLE=alice \
  MATRIX_DEVELOPER_TOOLS="codex claude-code opencode" \
  bash

Open the printed URL

The installer prints the URL, username, generated password, and code-server path. Store the initial password somewhere safe, then replace the edge auth with your preferred HTTPS and access-control setup.

Verify services

systemctl status matrix-gateway matrix-shell matrix-code nginx --no-pager
journalctl -u matrix-gateway -u matrix-shell -u matrix-code -n 200 --no-pager
sudo -u matrix bash

What You Get

Matrix web shell on your VPS.
Gateway API and WebSocket services protected by an internal bearer token.
Local owner-controlled Postgres on 127.0.0.1.
code-server behind the Matrix code proxy at /code/.
Persistent home directory at /home/matrix/home.
Optional Claude Code, Codex, OpenCode, and Pi CLI installs through Matrix tool packs.
Source-free install from a verified host bundle.

What You Manage

DNS and TLS.
Server firewalling, OS updates, and SSH access.
Backups and restore policy.
Upgrades to newer Matrix host bundles.
Edge auth hardening beyond the generated nginx Basic Auth.
Any external integration secrets.

Differences From Matrix Cloud

Capability	Matrix Cloud	Self-host preview
Provisioning	Managed VPS creation	Bring your own VPS
Auth	Clerk and platform sessions	Generated nginx Basic Auth
Routing	`app.matrix-os.com` and `code.matrix-os.com`	Your domain or server IP
Backups	Managed platform path	You configure backups
Updates	Platform release fan-out	Manual installer/update path
Integrations	Platform-owned Pipedream	Not configured by default
Mobile and desktop handoff	Upcoming managed surfaces	Not included yet

Security Notes

The shell runs in explicit standalone mode. Public browser access is expected to go through nginx, while same-origin API, file, app, and WebSocket requests are rewritten by the shell proxy with the internal MATRIX_AUTH_TOKEN. code-server runs loopback-only and is reached through a token-protected Matrix proxy.

IP-only installs are acceptable for first boot and private-network testing, but they are plain HTTP unless you add a trusted TLS/access layer. For a public VPS, prefer DNS plus TLS, Tailscale, Cloudflare Access/Tunnel, or another authenticated reverse proxy before storing long-lived work there.

Do not expose ports 3000, 4000, 8787, or 5432 publicly. Keep them on loopback and expose only your hardened reverse proxy.

The installer leaves GET /health open at nginx and returns only {"ok":true} so basic uptime monitors can check the public edge without credentials or gateway details. For deeper checks, use systemd status or local-only gateway health from the server.

Manual Install Telemetry

The installer sends lightweight, best-effort telemetry to Matrix OS so we can see how many people choose the manual path, which release channel/version they reach, whether installs finish, and where failures happen. The endpoint has a bounded request body and short-window rate limits to keep the signal useful. It records an anonymous install id, channel, installed version, IP-vs-DNS mode, default-vs-custom bundle source, selected developer-tool count, phase, status, and exit code.

It does not send your Matrix handle, password, auth tokens, Postgres password, domain name, project files, shell output, or code-server URL. The website telemetry endpoint also asks PostHog to discard client IP by setting $ip to 0.0.0.0.

Opt out per install:

curl -fsSL https://matrix-os.com/install-server.sh | sudo MATRIX_NO_TELEMETRY=1 bash

Or disable only installer telemetry:

curl -fsSL https://matrix-os.com/install-server.sh | sudo MATRIX_INSTALL_TELEMETRY=0 bash