Installation

One-Command Install

The fastest way to install HELIX Mission Control:

Linux / VPS (Ubuntu 20.04/22.04/24.04, Debian 11/12)

curl -fsSL https://helixnode.tech/install.sh | sudo bash

macOS (Apple Silicon or Intel)

curl -fsSL https://helixnode.tech/install.sh | bash

macOS Prerequisites

Docker Desktop must be installed and running before you run the installer. Download it from docker.com. Homebrew will be installed automatically if not present.

The installer will prompt you for:

• Domain name — your server's domain (or IP address)
• Admin email — for SSL certificates and your first login
• Admin password — password for the admin account
• AI model provider — which AI provider to use (Moonshot, OpenAI, Anthropic, NVIDIA, or custom)
• AI model API key — your API key for the selected provider

What the Installer Does

1. Pre-flight checks — verifies supported OS, 2GB+ RAM (Linux), 10GB+ disk, and port availability
2. System updates — installs required packages (curl, git, jq, etc.)
3. Docker setup — installs Docker Engine and Docker Compose if not present
4. Creates helix user — dedicated system user for running services
5. Clones repository — downloads HELIX Mission Control to /home/helix/helix-mission-control
6. Environment config — generates .env with your settings, auto-generates secrets (JWT, DB password, gateway token)
7. Builds containers — builds and starts all Docker services (PostgreSQL, Redis, Gateway, Backend, Frontend)
8. Database setup — tables are created automatically on first backend startup
9. SSL setup — configures Caddy reverse proxy with automatic Let's Encrypt SSL (if domain provided)
10. Systemd service — creates helix-mission-control service for auto-start on boot
11. Backup scheduling — sets up daily automated backups

Install Options

# With domain and SSL
curl -fsSL https://helixnode.tech/install.sh | sudo bash -s -- \
  --domain helix.mycompany.com \
  --email admin@mycompany.com

# HTTP only (no SSL)
curl -fsSL https://helixnode.tech/install.sh | sudo bash -s -- --skip-ssl

# Use external reverse proxy (skip Caddy)
curl -fsSL https://helixnode.tech/install.sh | sudo bash -s -- --skip-proxy

# Custom install directory
curl -fsSL https://helixnode.tech/install.sh | sudo bash -s -- \
  --install-dir /opt/helix

All Options

Flag	Description	Default
--domain <domain>	Domain for SSL	Prompted
--email <email>	Email for Let's Encrypt	Prompted
--skip-ssl	HTTP only, no SSL	false
--skip-proxy	Skip Caddy proxy	false
--branch <branch>	Git branch to install	main
--install-dir <path>	Installation path	/home/helix/helix-mission-control

Manual Installation

1. Clone and setup

git clone https://github.com/Xylement/helix-mission-control.git
cd helix-mission-control

2. Generate environment config

bash scripts/setup-env.sh

This creates .env with auto-generated secrets (JWT, database password, gateway token).

3. (Optional) Configure AI model now

Edit .env and set your AI model API key:

nano .env

Set MODEL_API_KEY to your API key. For a free Google Gemini key, visit aistudio.google.com/apikey.

You can also skip this and configure the model from the web UI after starting.

4. Start HELIX

docker compose up -d --build

This builds and starts all services (database, Redis, gateway, backend, frontend). First build takes 3-5 minutes.

5. Access the dashboard

Open http://localhost:3000 in your browser.

The onboarding wizard will guide you through:

• Creating your organization and admin account
• Activating a license (or starting a free trial)
• Configuring your AI model (if not done in step 3)
• Setting up departments and agents

6. Verify setup

Visit http://localhost:3000/setup-check to see if all services are running correctly.

Note: The database tables are created automatically on first startup — no separate migration step is needed.

Post-Install

After installation completes:

1. Access the dashboard at https://your-domain.com (or http://your-ip:3000)
2. Log in with the admin email and password you configured
3. Enter your license key in Settings > Billing (or start with the free trial)
4. Run the onboarding wizard to configure your organization

The installer creates a systemd service, so HELIX starts automatically on boot:

# Check service status
sudo systemctl status helix-updater.service

# View logs
sudo journalctl -u helix-updater -f

# Check HELIX containers
docker compose -f ~/helix-mission-control/docker-compose.yml ps

Updating

From the Dashboard (Recommended)

Go to Settings > System and click Check for Updates. If a new version is available, click Update Now and confirm with your password. The update runs automatically with progress tracking and auto-rollback on failure.

Note: This requires the update daemon to be running. On Linux, it's set up automatically by the installer. On macOS, use the manual method below.

Manual Update

cd ~/helix-mission-control
git pull origin main
docker compose up -d --build

Or use the update script:

cd ~/helix-mission-control
bash scripts/update.sh

Uninstalling

To completely remove HELIX:

cd ~/helix-mission-control
bash scripts/uninstall.sh

WARNING

This removes all containers, volumes (including the database), and configuration. Make a backup first if you want to keep your data.

Troubleshooting

API requests return "Not Found" or pages show loading forever

The frontend auto-detects the backend URL. If accessing on port 3000, it redirects API calls to port 8000. Behind a reverse proxy (port 80/443), it uses relative paths.

If auto-detection doesn't work, set the backend URL explicitly:

# Set explicit API URL in .env
echo "NEXT_PUBLIC_API_BASE_URL=http://YOUR-SERVER-IP:8000" >> .env

# Rebuild the frontend
docker compose up -d --build frontend

Visit http://localhost:3000/setup-check to diagnose connectivity issues.

Containers won't start on macOS

Docker Desktop must be running before starting HELIX. Also ensure file sharing is enabled for your home directory in Docker Desktop > Settings > Resources > File Sharing.

"Permission denied" on install

On macOS, don't use sudo:

# Correct (macOS):
curl -fsSL https://helixnode.tech/install.sh | bash

# Correct (Linux):
curl -fsSL https://helixnode.tech/install.sh | sudo bash

Update button doesn't work

The update daemon must be running:

sudo systemctl status helix-updater.service

If it's not running, reinstall it:

# See the systemd service setup in the install script
sudo systemctl enable helix-updater.service
sudo systemctl start helix-updater.service

On macOS, update manually:

cd ~/helix-mission-control
git pull origin main
docker compose up -d --build

Version shows 1.0.0 after install

Pull the latest code and rebuild:

cd ~/helix-mission-control
git pull origin main
docker compose up -d --build
cat VERSION  # Should show latest version