Linux App

Linux App

The Gateway is fully supported on Linux. Node is the recommended runtime. Bun is not recommended for the Gateway (WhatsApp/Telegram bugs).

Native Linux companion apps are planned. Contributions are welcome if you want to help build one.

Beginner quick path (VPS)

1. Install Node 24 (recommended; Node 22 LTS, currently 22.14+, still works for compatibility)
2. npm i -g velaclaw@latest
3. velaclaw onboard --install-daemon
4. From your laptop: ssh -N -L 18789:127.0.0.1:18789 <user>@<host>
5. Open http://127.0.0.1:18789/ and authenticate with the configured shared secret (token by default; password if you set gateway.auth.mode: "password")

Full Linux server guide: Linux Server. Step-by-step VPS example: exe.dev

Install

• Getting Started
• Install & updates
• Optional flows: Bun (experimental), Nix, Docker

Gateway

• Gateway runbook
• Configuration

Gateway service install (CLI)

Use one of these:

velaclaw onboard --install-daemon

Or:

velaclaw gateway install

Or:

velaclaw configure

Select Gateway service when prompted.

Repair/migrate:

velaclaw doctor

System control (systemd user unit)

Velaclaw installs a systemd user service by default. Use a system service for shared or always-on servers. velaclaw gateway install and velaclaw onboard --install-daemon already render the current canonical unit for you; write one by hand only when you need a custom system/service-manager setup. The full service guidance lives in the Gateway runbook.

Minimal setup:

Create ~/.config/systemd/user/velaclaw-gateway[-<profile>].service:

[Unit]
Description=Velaclaw Gateway (profile: <profile>, v<version>)
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/velaclaw gateway --port 18789
Restart=always
RestartSec=5
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
KillMode=control-group

[Install]
WantedBy=default.target

Enable it:

systemctl --user enable --now velaclaw-gateway[-<profile>].service