nazar-bridge 0.7.8

Nazar bridge daemon — relays phone prompts to local `claude -p` over a long-lived WebSocket.

nazar-bridge

nazar-bridge is a small, open-source daemon that lets you drive Claude Code on your own machine from the Nazar phone dashboard.

It holds a single long-lived outbound WebSocket connection to the Nazar API, registers your local Claude-Code project directories, and — when you send a prompt from your phone — spawns claude -p in the matching project and streams the output back. Nothing listens for inbound connections on your machine; the daemon dials out, so there are no ports to open.

The source is intentionally small and auditable — read it before you install it. That's the whole trust model (see Trust & supply chain).

---

Prerequisites

• Python 3.12+ on your machine.
• Claude Code installed and authenticated. The daemon shells out to the claude CLI using your logged-in session, so claude must be on your PATH and already signed in.
• A Nazar account on a Pro or Unlimited plan. The bridge is a paid-tier feature — the Free plan has no bridge and cannot mint daemon tokens.

---

Install

Recommended (isolated tool install via uv):

uv tool install nazar-bridge

Alternative (via pipx):

pipx install nazar-bridge

Upgrade later:

uv tool upgrade nazar-bridge      # or: pipx upgrade nazar-bridge

Both put a nazar-bridge command on your PATH.

---

Connect

1. Get a daemon token. In the Nazar dashboard, open /code → Bridge tokens and create one. It looks like nazar_bridge_xxxxxxxxxxxxxxxx. Copy it now — it's shown only once.

2. Configure the daemon with the token (and, if your API host differs from the default, the WebSocket URL):

   nazar-bridge configure --token nazar_bridge_xxxxxxxxxxxxxxxx
   # to point at a self-hosted / dev API instead of the default:
   nazar-bridge configure --token nazar_bridge_xxxx --api-url wss://your-host/api/bridge/ws
   

3. Register the project directories you want reachable from your phone:

   nazar-bridge add /path/to/your/project
   nazar-bridge add /path/to/another/project
   nazar-bridge list
   

4. Run it. Either start it once in a terminal:

   nazar-bridge run            # add --debug for verbose logs
   

   …or install it as a login autostart service (recommended — see below) so it reconnects automatically after a reboot.

run --once exits right after the first successful register — handy for smoke-testing a freshly-configured daemon.

---

Autostart at login (recommended)

Instead of leaving a terminal open, register the daemon to start at login and restart on failure. One cross-platform command detects your OS and writes the right unit:

nazar-bridge service install      # Windows / macOS / Linux
nazar-bridge service status       # is it installed / running?
nazar-bridge service uninstall    # remove it

OS	What service install creates
Windows	A Task Scheduler task "Nazar Bridge" that runs at logon (windowless).
macOS	A launchd LaunchAgent app.nazar.bridge in ~/Library/LaunchAgents.
Linux	A systemd --user unit nazar-bridge.service (enabled + started).

The service always runs as your own user (never root/SYSTEM) because the daemon spawns claude with your personal Claude Code login — service install refuses to run as root. On Linux, run loginctl enable-linger $USER if you want the daemon up even when you're not logged in interactively.

Logs go to the daemon's rotating log file (see below) regardless of how it's started. For live debugging, run nazar-bridge run in a terminal to watch output directly.

Windows note: earlier releases shipped scripts/install-windows-startup.ps1. That script still works and adds a richer restart policy, but nazar-bridge service install is now the recommended, cross-platform path.

---

Where config & logs live

OS	Config file	Daemon log
Windows	%APPDATA%\nazar-bridge\config.toml	%APPDATA%\nazar-bridge\daemon.log
macOS	~/.config/nazar-bridge/config.toml	~/.config/nazar-bridge/daemon.log
Linux	$XDG_CONFIG_HOME/nazar-bridge/config.toml or	…/nazar-bridge/daemon.log
	~/.config/nazar-bridge/config.toml

The token is stored plaintext in config.toml — it's the daemon's only credential. Protect it with filesystem permissions:

• Windows: icacls "%APPDATA%\nazar-bridge\config.toml" /inheritance:r /grant:r "%USERNAME%:F"
• macOS / Linux: chmod 600 ~/.config/nazar-bridge/config.toml

Rotating the token is two commands: nazar-bridge configure --force --token <new> (your project list is preserved).

---

Trust & supply chain

The bridge runs on your machine and runs Claude Code with full permissions, so its trustworthiness matters. The design keeps that auditable:

• Open source. Every line is on GitHub: arm-yan/nazar under apps/bridge. Read it before installing.
• Published from PyPI, not a private host. uv tool install nazar-bridge pulls the package and its only two runtime dependencies (websockets, pydantic) from PyPI. Nothing is downloaded from a private or vendor server.
• Signed provenance. Releases are published to PyPI via GitHub Actions Trusted Publishing (OIDC) with attestations — no long-lived upload token exists, and each artifact carries signed build provenance you can verify back to the tagged commit.

---

Security model

Be deliberate about what this daemon does:

• When a prompt arrives from your authenticated Nazar dashboard, the daemon spawns Claude Code with --dangerously-skip-permissions — Claude can read, write, and run commands in the registered project directory without per-action prompts. This is intentional: it's your machine, your Claude login, and your token, and the point of the bridge is hands-off remote execution.
• The trust boundary is your daemon token plus your single-user host. Anyone who holds the token can drive Claude on your machine through the Nazar API. Treat the token like an SSH key: keep config.toml locked down, and rotate/revoke the token (from the dashboard) if it leaks.
• The daemon only ever makes an outbound WebSocket connection — it opens no listening port on your machine.

If that posture isn't acceptable for a given machine, don't install the bridge there.

---

Wire protocol

The daemon and API speak JSON text frames over the WebSocket. The source of truth for the schemas is apps/api/nazar_api/schemas/bridge.py; the daemon's nazar_bridge/wire.py mirrors the relevant subset so the daemon stays installable independently of the API package.

---

Develop / test

cd apps/bridge
python -m pip install -e ".[dev]"
pytest
ruff check nazar_bridge tests
mypy nazar_bridge

Build the distributables locally:

python -m build          # produces dist/*.whl and dist/*.tar.gz
twine check dist/*