Installation

Download a build, or run ChungusHub from source.

Download

Builds for Windows, macOS (Apple Silicon) and Linux are on the releases page. Unpack one and run it: nothing is installed, and your data stays in the folder beside it. That is the whole install, and everything below is only for running from source.

The executable is not signed by a developer certificate, so Windows and macOS both stop it the first time. The README.txt in the folder says how to get past each.

Prerequisites

Bun, and nothing else: the server runs on Bun’s standard library alone and the database is SQLite.

Windows

powershell -c "irm bun.sh/install.ps1 | iex"

Run from source

1. Clone and install

   git clone https://github.com/patcireamo/ChungusHub.git
   cd ChungusHub
   bun install --frozen-lockfile
   
2. Start it

   Double-click start.bat on Windows or start.command on macOS. On Linux, run ./dev.sh.

   One launcher runs both halves, the client on port 1420 and the server on 4242. Open http://localhost:1420 once it is up. Q quits both. B rebuilds the client into build/, which is what port 4242 serves.

Build a portable copy

bun run package

This writes dist/ChungusHub-portable/: one executable with Bun embedded, the built client, and the presets, skills and backgrounds the app ships with. It is the same layout as a release build: it serves everything from port 4242, keeps its data beside the executable, and opens a browser on start.

Your data

Everything you create lives in user-data/: the database, uploaded images, presets, and the password hash if you set one. Back that folder up and you have backed up the whole workspace. Snapshots land in backups/ beside it. Nothing leaves the machine except the provider requests you configure.

Where that folder sits depends on how you started ChungusHub. A downloaded or packaged copy keeps it beside the executable. Run from source, it is created in the directory you launch from, which the launchers make the repository folder. A second clone therefore opens a second, empty workspace while the first one sits untouched where you left it. The server prints the path it is using as it starts, and Settings → About shows it with a button to copy it.

Two installs, one workspace. Point dataDir (below) at the same folder from both and a packaged copy and a copy run from source pick up where the other left off, with nothing to move across. Run one at a time: a second copy started while the first still has the folder refuses to start and names the one holding it, because two of them writing one database is how that database gets damaged. Opening a workspace with an older ChungusHub than the one that last wrote it is allowed and says so, on the server’s own output and in a bar across the top of the app; what it wrote before that upgrade is still in your snapshots.

Settings file

Everything ChungusHub has to know before it can answer anything is read from chungushub.config.json, which it writes beside the executable on its first run (beside the repository when you run from source):

{
  "port": 4242,
  "host": "0.0.0.0",
  "dataDir": "user-data",
  "backupDir": "../backups",
  "openBrowser": true,
  "allowedHostnames": []
}

Edit it in any text editor and start ChungusHub again. Absolute paths are taken as written; a relative one is read from the file’s own folder, except backupDir, which is read from the data folder, so snapshots stay beside the data when you move it. A value it cannot read stops the launch and names the line to fix, rather than starting somewhere nobody chose.

openBrowser decides whether starting ChungusHub throws a tab up. Set it to false and it just serves, which is what a machine you are not sitting at wants. Run from source it opens the hot-reloading app on port 1420 instead, and only the once, however often the server behind it restarts while you work.

allowedHostnames is for the one setup that needs it, and is empty for everyone else. ChungusHub answers to its own address, to localhost, and to this computer’s name, so reaching it the way this page describes needs nothing here. If you reach it by some other name instead, a Tailscale name or a domain you point at it through a proxy, add that name to this list, the name alone with no port or http://. Any name that is not on it is turned away with a page telling you what to add, which is what keeps a site you visit from reaching your workspace by pointing its own address at your computer.

A version that adds a setting adds its line to the file you already have, leaving every value in it as you wrote it, so there is never anything to copy across by hand. It says on screen which line it added.

A fresh install listens on this computer only: the port is opened on loopback and nothing on your network can see the workspace. To use it from a phone or another machine, turn on Network Access under Settings → Security, then choose who gets in with the IP allowlist and an optional password.