Sokuza ships as a single Node binary. Install it once, create a config, start it, and (optionally) wire it to auto-start on login. Everything stays on your machine.
Prerequisites
Same three commands on macOS, Linux, and Windows.
STEP 1
Install globally
$ npm install -g sokuza $ git clone https://github.com/<owner>/sokuza.git $ cd sokuza && npm install && npm run build $ npm link # puts the sokuza binary on your PATH
Sokuza is getting its first public release soon. Until it lands on npm, use the GitHub path — identical behavior, just a git clone in the middle. npm link works without root because it symlinks into your npm prefix; if that prefix needs sudo on your system, follow the prefix-fix guide first.
STEP 2
Create a config
$ mkdir -p ~/sokuza && cd ~/sokuza $ sokuza init
Writes sokuza.config.yaml from the bundled example. Open it, uncomment the integrations you want, and fill in tokens. The file can live anywhere — the engine reads it from the current working directory by default.
STEP 3
Start it
$ sokuza Binds port 24847 (falling back through 24848 – 24852 if busy). You'll see a 🚀 Sokuza is listening at http://localhost:24847 line.
One command installs the right kind of user-scoped service for your OS. No admin, no sudo, no daemon tooling to learn.
$ cd ~/sokuza # wherever your sokuza.config.yaml lives $ sokuza install-service
The absolute path to your config is baked into the service unit, so it doesn't matter what your PATH looks like at login time.
Tested on 13 Ventura and later. Intel and Apple Silicon.
LaunchAgent
~/Library/LaunchAgents/
ai.sokuza.plist
Logs: ~/.sokuza/logs/
systemd distros (Ubuntu, Debian, Fedora, Arch, NixOS). systemd --user is used — no sudo required.
systemd user unit
~/.config/systemd/user/
sokuza.service
Survive logouts: sudo loginctl enable-linger $USER
Windows 10 / 11. Task Scheduler logon task with automatic restart on crash — no admin required.
Scheduled task
Task name:
Sokuza
Manage via taskschd.msc or schtasks /Query /TN Sokuza.
Remove it
$ sokuza uninstall-service Unloads the unit and deletes the file. Sokuza itself stays installed — remove with npm uninstall -g sokuza.
Sokuza listens locally. To receive webhook deliveries from GitHub or Slack, expose it through a tunnel or a reverse proxy.
Development tunnels
Sokuza binds 127.0.0.1 by default, which is loopback-only — tunnels forward to it fine. Pick one:
$ npx -y localtunnel --port 24847 # or $ cloudflared tunnel --url http://localhost:24847 # or $ ngrok http 24847
Always-on
Put Sokuza behind your own Nginx / Caddy / Cloudflare Tunnel on a VPS or home server. Integrations verify signatures (GitHub webhook secret, Slack signing secret), so the public URL just needs to forward to 24847.
Exposing the port directly on your LAN requires setting server.host: "0.0.0.0" in the config — see the security note below.
Sokuza is local-first by default. The surface area you open up is your choice, made explicit in the config.
Default — loopback only
server: host: "127.0.0.1"
Dashboard, API, and webhooks are reachable only from the machine running Sokuza. A tunnel can still forward to localhost; that's how tunnels work.
Opt-in — LAN / all interfaces
server: host: "0.0.0.0"
Anyone who can route packets to your machine's IP can reach the dashboard and /api/*. Webhook endpoints verify integration signatures, but the dashboard has no auth in front of it today.
Set this only when running on a trusted network, a VPS with a firewall in front, or when you've added your own reverse-proxy auth layer.
Dashboard bearer token
The dashboard and /api/* routes are gated behind a bearer token. On first start, Sokuza generates a random 256-bit token and stores it at ~/.sokuza/dashboard-token (mode 0600) — no interaction needed.
The startup log prints a one-time link (http://localhost:24847/?t=…) that seeds the token into your browser's localStorage. From then on the dashboard unlocks silently. Lost the link? Run:
$ sokuza token # prints the current token and ready-to-paste URLs for running instances $ sokuza token --rotate # invalidates old tabs on next /api call; restart sokuza to pick up
/health stays unauthenticated — the public site only needs to know the app is running. Webhook endpoints verify integration signatures as before.
The public site (sokuza.ai) never proxies your data. It only probes /health to detect a running instance and then hands you off. Your config, tokens, and workflow output never leave your machine — the only way data flows outbound is through the integrations you explicitly enable (GitHub API, Slack API, Anthropic API).
Run sokuza status — it reads ~/.sokuza/instances/, probes each live pid on its bound port, and prints port, uptime, version, and health. The same data is available via curl -s http://127.0.0.1:24847/health if you want to verify manually.
sokuza logs picks the right source per platform: journalctl on Linux, ~/.sokuza/logs/ on macOS, and Event Viewer for Windows (Task Scheduler doesn't capture stdout by default). Pass -f to follow, -n 200 for more history.
Check sokuza status first — if it reports "stuck", the process is alive but the HTTP stack is wedged; restart sokuza. Otherwise check browser extensions: privacy blockers sometimes strip cross-origin requests to loopback. As a fallback, open http://localhost:24847 directly in a new tab.
Sokuza falls back through 24848 – 24852 automatically. The public site probes all six, so you do not need to configure anything. sokuza status shows the port that was actually bound; the same data is persisted to ~/.sokuza/instances/<pid>.json.
Run sokuza install-service once. On Linux, also run sudo loginctl enable-linger $USER if you want it alive when you are logged out.
For permanent setups, put Sokuza behind your own reverse proxy or VPN. For day-to-day development, pair it with localtunnel, cloudflared, or ngrok.
Nothing. The public site only probes /health, which returns {"app":"sokuza","ok":true,"version":"…"}. Your config, integrations, API keys, and workflow output never leave your machine.
sokuza uninstall-service, then npm uninstall -g sokuza. Delete ~/.sokuza/ and your project directory to remove state and logs.