# Lawang

> Local-first remote access for your own machine, with QR pairing and explicit host approval.

Run one command on your laptop or server, scan a QR code from your phone,
tablet, or another browser, then open a secure remote workspace for your
project. Lawang is built for developer workflows: terminal, files, code edit,
Git, localhost proxy, audit log, host controls, and an early remote desktop
mode.

No accounts. No central cloud dashboard. No broker that stores your command
output or project files. The host keeps control and must approve new devices.

```bash
npm i -g lawang
lawang start
```

Scan the QR shown in the terminal (or open `http://localhost:3999/qr` for
a fullscreen version), approve the request from the host CLI, and you're in.

## Features

### Remote terminal

- Browser terminal powered by xterm.js and `node-pty`.
- Mobile shortcut bar for `Esc`, `Tab`, `Ctrl+C`, arrows, and common shell keys.
- Reconnect-safe PTY: short disconnects keep the shell alive and replay buffered
  output when the browser returns.
- One-shot command chat tab for quick commands with formatted output, exit code,
  JSON, and diff rendering.

### Files and code

- Browse the project root from the browser.
- Read, edit, save, upload, rename, delete, and create folders inside the
  sandboxed root.
- Monaco editor for code editing directly from the remote browser.
- File preview protects large/binary files and blocks path traversal.

### Git workflow

- Git status, diff, and recent log.
- Stage and unstage files.
- Commit, pull, and push from the web UI.
- Push supports first-time upstream setup when the branch has no tracking
  branch.

### Remote desktop preview

- Desktop tab for screen viewing on macOS hosts.
- Mouse move/click, keyboard events, and text input when the session has
  `screen:control`.
- Responsive Fit/Large view modes for desktop and mobile browsers.
- macOS needs Screen Recording permission for viewing and Accessibility
  permission for control.

### Localhost proxy

- Expose local dev servers through the Lawang session, for example
  `localhost:3000` or `localhost:5173`.
- Access proxied apps under `/proxy/<port>/...`.
- Optional allow-list mode or open dev mode via `--proxy open`.

### Device and session control

- One-time QR pairing with explicit approval from the host CLI.
- Permission scopes: full access, read-only, or terminal-only.
- Trusted devices can skip future approval and can be revoked later.
- Optional `--auto-approve` mode for trusted environments where valid pairing
  tokens should skip the interactive host prompt.
- `--unattended` combines auto-approve with keep-awake for always-ready hosts.
- List and revoke active sessions from the CLI.
- Rotate the pairing token without restarting the agent.

### Host utilities

- Host power actions from the UI: sleep, shutdown, reboot, and lock.
- Battery indicator in the web session.
- `--keep-awake` mode to prevent sleep while the agent is running.
- Update banner when a newer npm version is available.

### Audit and safety

- Local JSONL audit log at `~/.lawang/audit.log`.
- Audit viewer in the browser with filters and search.
- Security smoke test via `lawang verify`.
- Rate limits, origin checks, hashed tokens, sandboxed file paths, and bounded
  WebSocket frames.

## Commands

```bash
lawang start [--keep-awake] [--no-tunnel] [--port 3999] [--root .]
lawang start --proxy 3000,5173    # expose selected local dev ports
lawang start --proxy open         # allow any localhost port in dev mode
lawang start --auto-approve       # skip host prompt for valid pairing tokens
lawang start --auto-approve --auto-approve-scope files
lawang start --unattended         # auto-approve + keep-awake

lawang rotate                     # new pairing token without restarting
lawang devices [--revoke <id>]    # manage trusted devices
lawang sessions [--revoke <id>]   # list or revoke active sessions
lawang history                    # past sessions from audit log
lawang verify                     # smoke-test security hard rules
lawang ping                       # check if agent is running
```

## Requirements

- Node.js `>= 18.17`
- Optional: `cloudflared` for public tunnel (`brew install cloudflared` on
  macOS).
- macOS and Linux for core terminal/file/Git features.
- Remote desktop preview currently targets macOS hosts.
- Windows compatibility exists but is not yet fully tested.

## Security

- Pairing token: random 24-byte base64url, SHA-256 hashed, one-time consumed.
- Session token: random 32-byte, hashed in memory.
- Permission scopes are enforced on every API and WebSocket path.
- Path traversal guard on all file endpoints.
- WebSocket Origin allowlist + 64 KB frame cap + 32 KB input cap.
- Rate limiting on pairing, file reads, writes, and desktop frames.
- All secrets stored as hashes; raw tokens only ever leave to legitimate
  client device.
- Audit log records pairing, sessions, file writes, Git actions, proxy access,
  power actions, and desktop control events.

Run `lawang verify` to confirm hard rules are still enforced.

## Publish notes

The npm package includes the built agent (`dist/`) and built web UI (`public/`).
If you are publishing a README-only update, npm still requires a new version:

```bash
cd packages/agent
npm version patch --no-git-tag-version
npm publish
```

## License

MIT.

## Links

- Full docs: see [`docs/DOCUMENTATION.md`](https://github.com/alfianm/lawang/blob/main/docs/DOCUMENTATION.md)
- API reference: see [`site/api.html`](https://github.com/alfianm/lawang/blob/main/site/api.html)
- PRD: see [`prd_remote_access_app.md`](https://github.com/alfianm/lawang/blob/main/prd_remote_access_app.md)
