npm package: @justin0713/opspilot
Description: CLI installer for OpsPilot Local — self-hosted SSH operations platform
Latest version: 1.1.6

# OpsPilot

OpsPilot is a Flask + Socket.IO based remote operations dashboard for SSH/Serial management, test execution, file transfer, and real-time collaboration (War Room).

## Features

- Multi-target SSH command execution (single/batch/streaming shell)
- Serial console sessions (when `pyserial` is installed)
- Target/group management and command favorites
- SFTP file browser and upload/download
- Reboot/Network/SSD test workflows
- Share links for outputs/test snapshots
- War Room collaboration:
  - shared terminal output
  - guest approval/control
  - chat (including rich text/image)
  - WebRTC voice signaling
- Local JSON persistence (no external database required)
- Offline frontend vendor assets under `static/vendor/`

## Project Structure

- `opspilot.py`: main startup entry (recommended)
- `web_app.py`: core Flask + Socket.IO app
- `ssh_agent.py`: SSH and connection pool logic
- `auth.py`: auth decorators and user helpers
- `templates/`: web UI templates (`index`, `login`, `collab`, `share`)
- `tests/`: reboot/network/ssd blueprints and test state handling
- `static/vendor/`: local frontend dependencies (React/Babel/Tailwind/xterm/socket.io/simple-peer/fonts)
- `*.json`: runtime/config/test/share/audit data files

## Requirements

- Python 3.9+ recommended
- Windows/Linux supported (some X11 and serial paths are platform-specific)

Install Python dependencies:

```bash
pip install -r requirements.txt
```

Optional:

- `pyserial` for serial console support
- `pyOpenSSL` for local certificate generation (if cert files are missing)

## Checkout Source Code

Clone by HTTPS:

```bash
git clone https://github.com/<org-or-user>/<repo>.git
cd <repo>
```

Clone by SSH:

```bash
git clone git@github.com:<org-or-user>/<repo>.git
cd <repo>
```

Checkout a specific branch:

```bash
git fetch --all --prune
git checkout <branch-name>
git pull --ff-only
```

Checkout a specific commit:

```bash
git fetch --all --prune
git checkout <commit-sha>
```

Create a working branch from current HEAD:

```bash
git switch -c <new-branch-name>
```

## Run

Default (HTTPS mode, auto cert handling):

```bash
python opspilot.py
```

HTTP mode:

```bash
python opspilot.py --http
```

Custom port:

```bash
python opspilot.py --port 6000
```

Then open:

- `https://<host-ip>:5000` (default)
- or `http://<host-ip>:5000` with `--http`

## Authentication

- Login page: `/login`
- Default credential in UI hint: `admin / admin` (change immediately in real environments)

## Notes

- This project currently uses Flask debug/dev server settings for convenience.
- Data is persisted in local JSON files; back them up regularly.
- Frontend dependencies are available locally in `static/vendor`, so UI can run without public CDN access.
- Security baseline (2026-02-27):
  - `llm_config.json` and `rooms.json` are local-only and ignored by git.
  - Runtime logs (`*.log`) must not be committed.
  - If secrets were ever committed, rotate credentials first, then rewrite history.

## Security and Git Hygiene

- Keep secrets in environment variables or local untracked files only.
- Never commit bot tokens, API keys, chat IDs, or runtime logs.
- For Telegram bridge operations:
  - restrict with `ALLOWED_USER_IDS` / `ALLOWED_CHAT_IDS`
  - keep shell mode behind explicit intent (`shell:`) and safety policy
  - monitor usage via `GET /api/telegram/bridge/metrics`
- If history rewrite is performed:
  - force-push is required
  - all collaborators must re-sync (`git fetch --all --prune` and reset/reclone)

## Troubleshooting

- If style looks broken, force refresh (`Ctrl+F5`) to clear old browser cache.
- If `Cannot access 'xxx' before initialization` appears, ensure latest templates are deployed and cache is cleared.
- If HTTPS certificate warnings appear, trust local cert for internal use or run with `--http` in trusted networks.