Self-host guide

Run your own HiBoss server

HiBoss has no hosted service. This guide takes you from an empty Cloudflare account to an agent question answered on your phone.

Before you start

A Cloudflare account with Workers, D1 and R2 enabled.
Node.js 18 or later, and git.
The HiBoss app on your iPhone or Mac (see Download).

1. Deploy the server

Clone the repository, install dependencies and create the configuration from the example:

git clone https://github.com/sunoj/hiboss.git
cd hiboss
cp server/wrangler.toml.example server/wrangler.toml
npm ci

cd server
npx wrangler login
npx wrangler d1 create hiboss-db
npx wrangler r2 bucket create hiboss-attachments

Copy the database_id printed by d1 create into server/wrangler.toml. If you do not host the web console, delete the CONSOLE_ORIGIN line there.

Deploy. This applies the database migrations first and stops if one fails, then publishes the Worker:

npm run deploy

Wrangler prints your server URL, for example https://hiboss-server.<your-subdomain>.workers.dev. You will use it below.

2. Set the bootstrap secret

The bootstrap secret lets the first machine create your boss account and enrol itself. Until it is set, the server refuses both. Generate a random value, keep it somewhere safe, and store it as a Worker secret:

openssl rand -hex 32
npx wrangler secret put BOOTSTRAP_SECRET

Paste the value when Wrangler asks for it. It only works while the server is empty: once you and your first machine exist, nobody can use it to bootstrap again.

3. Install the CLI

On the machine where your agents run:

curl -fsSL https://hiboss.org/install.sh | sh

Or build it from the repository with Rust: cd cli && cargo build --release, then put target/release/hiboss on your PATH.

4. Set up the first machine

hiboss setup --server https://hiboss-server.<your-subdomain>.workers.dev \
  --bootstrap-secret <your-secret> --boss-name "Your Name"

You can pass the secret through the HIBOSS_BOOTSTRAP_SECRET environment variable instead of the flag. The CLI never prints it. --boss-name is the name the apps show for you; without it, the CLI uses your account name or asks.

On an empty server, setup creates your boss account and prints a pairing link, a QR code of that link, the pairing code and when it expires. The code works once and expires after five minutes. Setup then asks the server to enrol this machine and waits for your approval.

5. Pair your iPhone or Mac

iPhone: open HiBoss, tap Scan a code and scan the QR code in your terminal.
Mac: open HiBoss, go to Settings → Connection, choose Pair with Code… and paste the link or code.

Pairing gives the app its own device credential, stored in the Keychain. The link carries your server address and the one-time code, never a token. Once one device is paired, you can add the other from it: Pair another device in iPhone Settings, or Sign in with iPhone on the Mac.

6. Approve the machine

The app shows the machine's request with a six-digit code. Check that it matches the code in your terminal, then approve. Setup finishes and saves the machine's profiles. If setup was interrupted, run hiboss setup again to resume the same request.

hiboss setup --check

7. Connect your agents

hiboss setup agents          # guidance for Claude Code and Codex
hiboss setup hooks --global  # Claude Code hooks for your replies
hiboss send "Hello from my agent"
hiboss ask --option "Yes" --option "No" "Did this reach your phone?"

The question appears in the app; your answer returns to the terminal. The agent guide covers the rest.

More machines

On a configured machine, run hiboss device invite --copy and paste the prompt into an agent on the new machine. It installs the CLI if needed, runs setup and waits for your approval in the app.

Telegram and Discord (optional)

The apps are enough on their own. If you also want messages in a chat app, run a guided setup:

hiboss setup telegram
hiboss setup discord

Or configure a channel directly, for example a Discord webhook:

hiboss channel set discord --webhook-url <WEBHOOK_URL>

When the Telegram wizard uses a webhook secret, it reminds you to store the same value on the server: npx wrangler secret put TELEGRAM_WEBHOOK_SECRET.

Push notifications

Push to the App Store iPhone app works out of the box. A server without its own Apple Push Notification service (APNs) key sends notifications through the HiBoss push relay at push.hiboss.org, which holds the app's APNs key.

The content stays end-to-end encrypted between your server and your iPhone: the iPhone app creates a key and gives it only to your server, and the relay and Apple see a generic alert and ciphertext. The relay sees your server's IP address, the install's random handle and the timing of each push.

To turn the relay off, set PUSH_RELAY_URL = "off" in [vars] of server/wrangler.toml; the iPhone app then says push is unavailable for this server. To push directly instead, set APNS_KEY_ID, APNS_TEAM_ID and the APNS_AUTH_KEY secret. A server with its own key never uses the relay. A direct key must belong to the Apple team that signs the app, so it fits a build of your own. With the relay, Live Activities update while the app is open.

Updating

git pull
npm ci
cd server && npm run deploy

Migrations are applied before the new Worker is published.

Stuck? See Support.