Metadata-Version: 2.4
Name: nazar-bridge
Version: 0.2.0
Summary: Nazar bridge daemon — relays phone prompts to local `claude -p` over a long-lived WebSocket.
Author: Arman
Maintainer: Arman
License-Expression: MIT
Project-URL: Homepage, https://github.com/arm-yan/nazar
Project-URL: Repository, https://github.com/arm-yan/nazar
Project-URL: Issues, https://github.com/arm-yan/nazar/issues
Keywords: nazar,claude,claude-code,daemon,websocket,bridge,ai-assistant,remote-control
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: websockets<17,>=15
Requires-Dist: pydantic<3,>=2
Provides-Extra: dev
Requires-Dist: pytest==9.0.3; extra == "dev"
Requires-Dist: pytest-asyncio==1.3.0; extra == "dev"
Requires-Dist: ruff==0.15.12; extra == "dev"
Requires-Dist: mypy==2.1.0; extra == "dev"
Dynamic: license-file

# nazar-bridge

`nazar-bridge` is a small, open-source daemon that lets you drive
[Claude Code](https://claude.com/claude-code) on your own machine from the
[Nazar](https://github.com/arm-yan/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](#trust--supply-chain)).

---

## Prerequisites

- **Python 3.12+** on your machine.
- **[Claude Code](https://claude.com/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](https://docs.astral.sh/uv/)):

```bash
uv tool install nazar-bridge
```

Alternative (via [pipx](https://pipx.pypa.io/)):

```bash
pipx install nazar-bridge
```

Upgrade later:

```bash
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):

   ```bash
   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:

   ```bash
   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:

   ```bash
   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:

```bash
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](https://github.com/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

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

Build the distributables locally:

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