Natroc

Personal AI Gateway — an always-on local daemon that bridges messaging channels (Telegram, WhatsApp) and a Web/CLI client to LLM providers (OpenRouter, Ollama). One global install, no native dependencies.

Requirements

• Node.js 24+ — required for node:sqlite and the global WebSocket runtime
• macOS, Linux, WSL, or Windows
• ~50 MB for the package + ~10 MB for runtime state under ~/.natroc/

Install

Quick start (one command)

Linux / macOS / WSL

curl -fsSL https://raw.githubusercontent.com/Licentora/natroc/refs/heads/main/install.sh | sh

Windows (PowerShell)

powershell -c "irm https://raw.githubusercontent.com/Licentora/natroc/refs/heads/main/install.ps1 | iex"

Direct npm install

If Node 24+ is already on your PATH:

npm install -g natroc

Install from source (developer mode)

The installer can clone, build, and link from the GitHub repo in one step:

NATROC_INSTALL_METHOD=git curl -fsSL https://natroc.ai/install.sh | sh

Or do it manually:

git clone https://github.com/Licentora/Natroc.git
cd Natroc
npm install
npm run all:install
npm run all:build
npm link

Install behind a restricted environment

If you cannot write to the global npm prefix:

npm config set prefix "$HOME/.local"
export PATH="$HOME/.local/bin:$PATH"
npm install -g natroc

First run

natroc setup

One command does everything:

1. Initializes ~/.natroc/ (database, vault, sessions, logs)
2. Migrates the schema
3. Installs a platform service (systemd user unit on Linux, LaunchAgent on macOS, scheduled task on Windows)
4. Starts the gateway on 127.0.0.1:37789
5. Prints the Web UI URL and returns to your shell

The service then runs in the background. Open http://127.0.0.1:37789 in your browser to create your account and configure providers.

Re-running natroc setup is idempotent — it skips steps that are already done.

What gets installed

Package files

| Path | Purpose | | --------------------------------------- | ------------------------------------- | | <npm-prefix>/lib/node_modules/natroc/ | Package code (server, UI bundle, CLI) | | <npm-prefix>/bin/natroc | CLI symlink |

Runtime state (~/.natroc/)

| Path | Purpose | | -------------------------------- | --------------------------------------------------------------------------------------- | | data/natroc.sqlite | All app state — users, conversations, memories, providers, channel bindings, usage logs | | vault/master.key | Master encryption key for all secrets | | vault/ | Encrypted provider tokens (OpenRouter, etc.) | | home/ | Markdown context files surfaced to the agent (USER.md, MEMORY.md, …) | | sessions/whatsapp-<accountId>/ | Baileys auth state for each WhatsApp account | | sessions/telegram-<botId>/ | Bot metadata for each Telegram bot | | logs/ | Service stdout / stderr | | cli-token | Optional CLI session token, created on demand by natroc cli-token |

Platform service files

| OS | Location | | ----------- | ------------------------------------------------ | | Linux / WSL | ~/.config/systemd/user/natroc.service | | macOS | ~/Library/LaunchAgents/ai.natroc.gateway.plist | | Windows | Scheduled Task Natroc |

CLI commands

| Command | Description | | ------------------------------------------------------------------- | -------------------------------------------------------- | | natroc setup | One-shot init + service install + start (idempotent) | | natroc doctor | Runtime diagnostics | | natroc server [--host H] [--port P] | Run the gateway in the foreground (bypasses the service) | | natroc daemon install\|uninstall\|status | Manage the platform service manually | | natroc cli-token | Generate a session token for natroc agent | | natroc agent --message "..." | Talk to the running daemon via WebSocket | | natroc agent --message "..." --to PEER --account ID | Talk and deliver the reply to a channel peer | | natroc chat "message" | Talk locally (no daemon required) | | natroc providers list\|connect-ollama\|connect-openrouter\|active | Manage LLM providers | | natroc memory [--query TEXT] | Inspect memory entries | | natroc improve [conversation-id] | Generate improvement proposals | | natroc proposals list\|approve\|reject | Manage proposals | | natroc home path\|show <file> | Inspect home context files |

Configuration

Natroc reads four environment variables. Everything else is stored encrypted in the vault and configured through the Web UI.

| Variable | Default | Purpose | | -------------------- | ----------- | ----------------------------------------- | | NATROC_HOME | ~/.natroc | Root directory for runtime state | | NATROC_SERVER_HOST | 127.0.0.1 | Gateway bind address | | NATROC_SERVER_PORT | 37789 | Gateway port | | NATROC_TOKEN | — | Session token override for natroc agent |

Channels

Telegram

1. Talk to @BotFather on Telegram and create a bot to obtain a token.
2. In the Web UI: Config → Channels → Add Telegram account; paste the token.
3. Click Connect. The bot starts long-polling immediately.
4. Add a binding (peer → agent) and message your bot.

WhatsApp

1. In the Web UI: Config → Channels → Add WhatsApp account.
2. Click Connect. A QR code appears in the account details.
3. On your phone: WhatsApp → Linked Devices → Link a device, then scan the QR.
4. Add a binding and message the linked number.

Auth state is stored per account in ~/.natroc/sessions/. Removing a session folder forces a fresh QR scan or token rotation on next connect.

Updating

npm install -g natroc@latest
natroc daemon uninstall
natroc setup

Data in ~/.natroc/ persists across upgrades.

Uninstall — full wipe

⚠️ Warning: removing ~/.natroc/ is irreversible. Provider tokens, conversations, memories, and channel sessions are unrecoverable without the master key in ~/.natroc/vault/.

One-liner

Linux / macOS / WSL

natroc daemon uninstall 2>/dev/null || true
npm uninstall -g natroc 2>/dev/null || true
rm -rf ~/.natroc
echo "Natroc fully removed."

Windows (PowerShell)

natroc daemon uninstall 2>$null
npm uninstall -g natroc 2>$null
Remove-Item -Recurse -Force $HOME\.natroc -ErrorAction SilentlyContinue
Write-Host "Natroc fully removed."

Step by step

1. Stop and remove the service

natroc daemon uninstall

If the natroc binary is missing or broken, remove the service manually:

Linux / WSL

systemctl --user disable --now natroc.service 2>/dev/null || true
rm -f ~/.config/systemd/user/natroc.service
systemctl --user daemon-reload

macOS

launchctl bootout "gui/$(id -u)/ai.natroc.gateway" 2>/dev/null || true
launchctl unload ~/Library/LaunchAgents/ai.natroc.gateway.plist 2>/dev/null || true
rm -f ~/Library/LaunchAgents/ai.natroc.gateway.plist

Windows (PowerShell)

schtasks /End /TN Natroc 2>$null
schtasks /Delete /F /TN Natroc 2>$null

2. Uninstall the global package

npm uninstall -g natroc

3. Remove all data

Linux / macOS / WSL

rm -rf ~/.natroc

Windows (PowerShell)

Remove-Item -Recurse -Force $HOME\.natroc

4. Verify

Linux / WSL

which natroc                                  # not found
systemctl --user list-units 'natroc*'         # 0 loaded units
ls ~/.config/systemd/user/natroc.service      # No such file
ls ~/.natroc                                  # No such file
ss -tlnp | grep 37789                         # empty

macOS

which natroc                                  # not found
launchctl list ai.natroc.gateway              # service not found
ls ~/Library/LaunchAgents/ai.natroc.gateway.plist
ls ~/.natroc
lsof -i :37789                                # empty

Windows (PowerShell)

Get-Command natroc                            # CommandNotFoundException
schtasks /Query /TN Natroc                    # cannot find
Test-Path $HOME\.natroc                       # False
Get-NetTCPConnection -LocalPort 37789         # empty

5. (Optional) Clear the npm cache

npm cache clean --force

Development

git clone https://github.com/Licentora/Natroc.git
cd Natroc
npm install
npm run all:install
npm run all:build
node server/dist/cli.js setup

For UI development with hot reload:

cd ui && npm run dev   # Vite at :5173, proxies /gateway to :37789

Type-check both projects:

npm run server:typecheck
npm run ui:typecheck

Architecture

A single long-running gateway daemon binds to 127.0.0.1:37789 and serves:

• WebSocket RPC at /gateway — frame protocol { type: connect | req | res | event | cancel }
• Static Web UI at / with SPA history fallback
• Placeholder canvas / A2UI surfaces at /__natroc__/canvas/ and /__natroc__/a2ui/

The daemon owns all messaging channel sessions (Telegram via grammy, WhatsApp via Baileys) and routes inbound messages through the agent loop, applying DM/group policies and shared memory injection before calling the configured LLM provider.

License

MIT