Skip to main content

Getting Started

Welcome to the Cyrus Panel documentation! Cyrus Panel is an open-source server and infrastructure management platform designed to deliver a fast, responsive Next.js frontend, a powerful Node.js API, and direct Docker socket orchestration via the Cyrus Daemon.

Before installing, review the prerequisites and choose the installation method that best matches your deployment.

Prerequisites​

1. Node.js Runtime​

Cyrus Panel requires Node.js v21 or newer.

  • Tested & recommended version: v24.19.0
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install 24.19.0
nvm use 24.19.0

Installing via Linux Package Managers​

sudo apt update
sudo apt install -y nodejs npm unzip
Verify Version

Always verify your active Node.js version before proceeding:

node -v # Must output v21.0.0 or higher

2. MongoDB Database​

Cyrus Panel stores users, server configs, vouchers, and telemetry inside MongoDB. You will need either:

  • A free cloud database instance from MongoDB Atlas (mongodb+srv://...).
  • A self-hosted local MongoDB instance (mongodb://127.0.0.1:27017/cyrus).

Choosing an Installation Method​

You can install Cyrus Panel using either the pre-built release archive (easiest & recommended) or by cloning from source (if you want to customize the frontend or contribute).

Every official release includes a pre-compiled panel.zip with the Next.js frontend already built into static assets. No build step is required.

  1. Download the latest release archive:
curl -L -o panel.zip https://github.com/HasenDev/cyrus-panel/releases/latest/download/panel.zip
  1. Extract the archive and navigate into the directory:
unzip panel.zip -d cyrus-panel
cd cyrus-panel
  1. Install production dependencies:
npm install --omit=dev
  1. Start the panel and launch the setup wizard:
npm run start

Method B: Installing From Source​

If you want to modify code or build directly from the latest Git commits:

  1. Clone the repository:

    git clone https://github.com/HasenDev/cyrus-panel.git
    cd cyrus-panel
    npm install

  2. Initialize the Frontend Submodule: Cyrus Panel uses a Git submodule for the Next.js user interface. Initialize it before building:

    git submodule update --init --recursive

  3. Build the Frontend Assets:

    npm run build

    This compiles the Next.js frontend into ./frontend/out and copies the static assets directly into ./src/frontend for the API to serve.

  4. Start the Panel:

    npm run start

Keeping Cyrus Panel Updated​

Need to upgrade an existing installation to a newer release? Check out the Updating Cyrus Panel guide.

Interactive First-Time Setup Wizard​

If Cyrus Panel does not detect an existing .env configuration file, starting the server (npm run start) will automatically launch the Interactive Setup Wizard in your terminal:

┌─────────────────────────────────────────────────────────────┐
│                  CYRUS PANEL SETUP WIZARD                   │
└─────────────────────────────────────────────────────────────┘

The wizard will interactively configure and test your environment:

  • Bind Host & Port: Configure the local listening address and port (default is 57777).
  • Public Panel URL & Reverse Proxy: Set your public domain with SSL. See our Cloudflare Tunnels or Nginx Reverse Proxy guides.
  • MongoDB Connection URI: Connects and verifies database connectivity. See the MongoDB Configuration Guide.
  • JWT Secret: Generates a cryptographically secure token signing secret automatically.
  • Google reCAPTCHA: Spam and bot protection for registration and login. See the reCAPTCHA Setup Guide.
  • Email Delivery: Transactional emails via Resend (for now). See the Mail Configuration Guide.
  • OxaPay Payment Gateway: Automated crypto billing and account balance top-ups. See the Payments Setup Guide.

Running Cyrus Panel Persistently (PM2)​

To keep Cyrus Panel running in the background and ensure it automatically restarts if the system reboots or crashes, use PM2 (Process Manager 2).

1. Install PM2 Globally​

npm install -g pm2

2. Start Cyrus Panel with PM2​

Inside your cyrus-panel directory, start the panel process:

pm2 start npm --name "cyrus-panel" -- run start

3. Enable Startup on Boot​

Save your current running process list and generate the startup script:

pm2 save
pm2 startup
Startup Command

If pm2 startup outputs a specific command to run with sudo, copy and run that command in your terminal to complete the systemd service registration.

Common PM2 Commands​

ActionCommand
View Live Logspm2 logs cyrus-panel
View Process Statuspm2 status
Restart Panelpm2 restart cyrus-panel
Stop Panelpm2 stop cyrus-panel
Delete from PM2pm2 delete cyrus-panel