Self-Hosting & Production

By default, RootCX manages the infrastructure for you -- create a project on rootcx.com and a dedicated Core instance is provisioned automatically. This guide is for teams that need to run the Core on their own servers.

The RootCX Core is a single binary that manages bundled PostgreSQL and Bun runtimes from a resources directory. Everything below covers running it standalone, deploying for a team, and hardening for production.

Core standalone setup

Download the binary for your platform and start it:

./rootcx-core

The daemon listens on http://localhost:9100 by default. On first boot it initializes the bundled PostgreSQL database automatically.

Verify it is running:

curl http://localhost:9100/health
# → {"status":"ok"}

Reverse proxy (TLS termination)

The Core itself does not terminate TLS. Place a reverse proxy in front of it to handle HTTPS:

nginx example:

server {
    listen 443 ssl;
    server_name core.yourcompany.com;

    ssl_certificate     /etc/ssl/certs/core.pem;
    ssl_certificate_key /etc/ssl/private/core.key;

    location / {
        proxy_pass http://127.0.0.1:9100;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # SSE logs endpoint needs long-lived connections
    location ~ /api/v1/apps/.+/logs {
        proxy_pass http://127.0.0.1:9100;
        proxy_set_header Host $host;
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 3600s;
    }
}

Caddy example:

core.yourcompany.com {
    reverse_proxy localhost:9100
}

Caddy handles TLS certificates automatically via Let's Encrypt.

Service registration

Register the Core as a system service so it starts on boot and restarts on failure.

systemd (Linux)

Create /etc/systemd/system/rootcx.service:

[Unit]
Description=RootCX Core
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/rootcx-core
Restart=on-failure
RestartSec=5
User=rootcx
Environment=RUST_LOG=info

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable rootcx
sudo systemctl start rootcx

launchd (macOS)

Create ~/Library/LaunchAgents/com.rootcx.core.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.rootcx.core</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/rootcx-core</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/com.rootcx.core.plist

Environment variables

Zero configuration is needed for local development. All variables are optional.

For production, provide explicit values for ROOTCX_JWT_SECRET (minimum 32 characters) and ROOTCX_MASTER_KEY (hex-encoded 32 bytes) instead of relying on auto-generated secrets. Set ROOTCX_BIND to expose the API beyond localhost.

PostgreSQL: bundled vs external

By default, the Core manages a bundled PostgreSQL instance. The database is initialized automatically on first boot and managed entirely by the daemon.

You can connect directly for debugging:

psql -h 127.0.0.1 -p 5480 -U postgres postgres

The bundled PostgreSQL is suitable for production workloads. For teams that require a managed database (RDS, Cloud SQL, etc.), set the DATABASE_URL environment variable to point at an external PostgreSQL instance. The bundled PostgreSQL will not be started.

Health check endpoints

Use these endpoints for load balancer health checks, monitoring, and uptime probes:

# Liveness probe
curl http://localhost:9100/health

# Full status with subsystem details (JSON)
curl http://localhost:9100/api/v1/status

The /health endpoint returns {"status":"ok"} when the daemon is ready. The /api/v1/status endpoint returns detailed information about PostgreSQL, the runtime, and any active Forge session.

Platform binaries

Binary per platform (requires bundled PostgreSQL and Bun in the resources directory):