Docs

The requirements and current commands to install Beluga as a permanent service on a Linux server, then connect Claude, Codex or Cursor from the interface.

The archive goes through the support window. The same code remains freely cloneable from the public repository.

Getting started

The install in six commands

Run them in order on a Linux server. They clone the public repository, build the app, create access and install the permanent service and its watchdog.

Install Beluga
git clone https://github.com/haikostudio/belugabuildtool.git beluga
cd beluga
npm install
npm run build
node scripts/set-credentials.mjs
sudo scripts/installer-services.sh

Beluga then listens locally on 127.0.0.1:7070. A reverse proxy such as Caddy can expose it on your domain with HTTPS.

01

A machine that stays on

You need a Debian or Ubuntu Linux server, Node.js 22 or later, and git. A reverse proxy such as Caddy is only needed for a public HTTPS address.

02

The public repository

The public repository clones over HTTPS without an invitation. The archive offered here contains the same project for anyone who prefers a direct download.

03

An AI tool on your server

Install at least one supported command-line tool: Claude Code, Codex or Cursor. The setup assistant shows what is missing on the machine.

04

Your own accounts

Connect Claude or Codex from the interface, or add a Cursor key. Several accounts for one engine can then share work according to availability.

Troubleshooting

When something breaks

The three failures that come up most often, each answered in one line.

01

The service starts, then stops

Read its state and logs with systemctl and journalctl to identify the path, user or dependency that is blocking it.

02

The build stops on "tsc: not found"

Reinstall dependencies with NODE_ENV=development npm install --include=dev, then run npm run build again.

03

No engine is ready

The setup assistant says whether the tool is missing or the account must be reconnected. Follow the displayed command, then return to the interface.

Ready to install?

Download the archive or clone the public repository, then follow the six commands in order.