Quick deployment

This path gets the Keragi server and web client running with the fewest steps. See the following pages for full installation, configuration and operations details.

1. Requirements

• Linux x86_64 (the current service host platform)
• Node.js 18 or newer
• A writable deployment directory
• SQLite by default, with no separate database service required

Other server platforms (Windows, macOS, ARM64, ESP32 and more) and external databases are planned for later versions. See Runtime and database.

2. Install the service host

Download keragi-wasmx-linux-x64.tgz from the downloads page, put it in the same directory as the resource packs you need, then install:

npm install -g ./keragi-wasmx-linux-x64.tgz

The current release is installed offline from the .tgz files; npm currently provides the host and userx; other resource packs will be available in a later version.

3. Initialize the deployment

wasmx init ./keragi-deploy
cd keragi-deploy
cp .env.example .env

Edit .env:

• JWT_SECRET: at least 32 random characters, shared by the host and userx
• BOOTSTRAP_ADMIN_CREDENTIAL / BOOTSTRAP_ADMIN_PASSWORD: initial administrator
• USERX_ADMIN_URL / USERX_PUBLIC_URL: how the host reaches userx
• WASMX_ADDR: listen address, defaults to 127.0.0.1:3001

4. Add WASM resources

The host and every WASM resource are independent packages, so you can combine them for your server role.

Typical main server:

wasmx add ../keragi-resx.tgz
wasmx add ../keragi-msgx.tgz
wasmx add ../keragi-userx.tgz

Connector server:

wasmx add ../keragi-conn.tgz

AI server:

wasmx add ../keragi-agix.tgz

Or use a preset:

wasmx init ./connector --preset connector --offline ..   # host + conn
wasmx init ./main --preset main --offline ..             # host + resx + msgx + userx
wasmx init ./full --preset full --offline ..             # host + all resources

--offline points to the directory containing the .tgz files; the example assumes the resource packs and the deployment directory are siblings.

5. Start and verify

wasmx start
wasmx status

The host listens on http://127.0.0.1:3001 by default. Check /status:

curl http://127.0.0.1:3001/status

Logs are written to wasmx.log; the database lives under data/ by default.

6. Deploy the web client

Download keragi-app-web.tar.gz from the downloads page:

1. Extract it and serve dist/ from any static server (with SPA fallback to index.html).
2. Copy config.example.json to dist/config.json.
3. Point services.userx, services.msgx, services.agix and services.conn at your server.
4. Reload the page.

Next steps

• Install the server: directory layout and start/stop details.
• Configuration: wasmx.json, .env, ports and secrets.
• WASM resource packs: selective install and upgrades.
• Deploy the web client: static hosting and config.json.