Install the server

The Keragi server consists of a wasmx host plus on-demand WASM resources. The host runs the resources and does not contain business source code.

1. Requirements

• Linux x86_64 (the only supported server platform today)
• Node.js 18+ (for the @keragi/wasmx installer; the host itself does not depend on Node.js)
• A writable directory for configuration, database and logs
• Database: SQLite by default, with no separate database service required

Windows, macOS, Linux ARM64 and ESP32 support is planned for later versions, as are external databases such as PostgreSQL / MySQL. See Runtime and database for the full support matrix.

2. Install the host

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

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

This provides the wasmx command.

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

Directory layout:

keragi-deploy/
├── wasmx             # prebuilt host binary
├── wasmx.json        # resource list and userx admin config
├── .env.example      # configuration template
├── start.sh          # start in the background
├── stop.sh           # stop
├── wasm/             # installed WASM resources
└── data/             # database and runtime data

4. Configure .env

cp .env.example .env

At minimum, review:

• WASMX_ADDR: listen address, defaults to 127.0.0.1:3001
• WASMX_DB: SQLite path, defaults to sqlite://data/clientx.db
• 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
• USERX_ADMIN_CREDENTIAL / USERX_ADMIN_PASSWORD: administrator credentials for userx

Generate a random secret:

openssl rand -base64 48

5. Install resources

The host and every WASM resource are independent packages. Combine them for your server role:

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

Common combinations:

Or use a preset:

wasmx init ./connector --preset connector --offline ..
wasmx init ./main --preset main --offline ..
wasmx init ./full --preset full --offline ..

Use wasmx list to inspect the installed resources.

6. Start, stop and check status

wasmx start
wasmx status
wasmx stop

• Logs: wasmx.log in the deployment directory
• Data: data/ by default
• Health check: curl http://127.0.0.1:3001/status

7. Expose the service

The host only listens on 127.0.0.1 by default. To let a web client on another machine connect:

1. Change WASMX_ADDR to 0.0.0.0:3001 (or the reverse-proxy address);
2. Configure HTTPS / a reverse proxy;
3. Put the public address into the web client’s config.json;
4. Do not expose administrative interfaces to untrusted networks.

Licensing: Keragi uses a proprietary software license; current versions grant limited rights under the included LICENSE. Later versions may offer subscription or commercial licensing for some host features or specific WASM resources; see Licensing and pricing.

Next steps

• Configuration: wasmx.json and resource prefixes.
• WASM resource packs: installation and upgrades.
• Deploy the web client: static hosting and config.json.