Metadata-Version: 2.4
Name: configstash-agent
Version: 0.1.0
Summary: Lightweight agent that backs up network device configs (MikroTik, Ubiquiti) to ConfigStash
Author-email: ConfigStash <support@configstash.io>
License-Expression: MIT
Project-URL: Homepage, https://configstash.io
Project-URL: Source, https://github.com/configstash/configstash-agent
Project-URL: Issues, https://github.com/configstash/configstash-agent/issues
Keywords: network,backup,mikrotik,routeros,ubiquiti,edgerouter,unifi,config-backup,netmiko
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: netmiko>=4.4.0
Requires-Dist: click>=8.1.7
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: requests>=2.32.4
Requires-Dist: croniter>=3.0.3
Dynamic: license-file

# ConfigStash Agent

A small on-premise collector that backs up your network device configs
(MikroTik RouterOS, Ubiquiti EdgeRouter/EdgeSwitch/UniFi Switch) to your
ConfigStash server.

**Your device credentials never leave your network.** The agent connects to
devices over SSH locally and pushes only the resulting config text to the API
over outbound HTTPS, authenticated with an agent token. No inbound ports needed.

## Quick Start: from zero to first backup in 5 minutes

**Prerequisites:** Python 3.12+, a ConfigStash account, SSH access to at least one device.

### 1. Install (30 sec)

```bash
pip install git+https://github.com/configstash/configstash-agent.git
```

### 2. Get an agent token (1 min)

In the ConfigStash web UI: **Settings → Agents → Create agent**.
Copy the token (`cst_agent_...`) — it is shown only once.

### 3. Initialize (30 sec)

```bash
configstash-agent init
```

Enter your API URL (e.g. `https://api.yourdomain.com`) and the agent token.
This creates `~/.configstash/config.yaml` (permissions `600`).

### 4. Add a device (1 min)

In the web UI: **Dashboard → Add device**. Copy the device ID it shows, then
add the device to `~/.configstash/config.yaml`:

```yaml
devices:
  - name: "Office MikroTik"
    device_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"   # from the web UI
    host: 192.168.88.1
    device_type: mikrotik_routeros    # mikrotik_routeros | ubiquiti_edgerouter | ubiquiti_edgeswitch | ubiquiti_unifiswitch
    username: admin
    password: "your-ssh-password"
    port: 22
```

> Tip: create a dedicated read-only SSH user on the device for backups.

### 5. Test and run (2 min)

```bash
configstash-agent test    # dry run: SSH connect + collect, nothing sent
configstash-agent run     # collect and upload your first backup
```

Open the web UI — your backup is there. Done. 🎉

### 6. Keep it running

```bash
configstash-agent install-service   # auto-start on boot (systemd / launchd)
```

By default backups run every 6 hours (`schedule: "0 */6 * * *"` — standard
cron syntax, edit in config.yaml) with a heartbeat every 5 minutes.

## No devices yet? Try demo mode

```bash
configstash-agent demo --api-url https://api.yourdomain.com --token cst_agent_... --repeat 3
```

Creates a virtual MikroTik and uploads realistic configs with changes between
runs — great for seeing the diff viewer in action.

## All commands

| Command | What it does |
|---------|--------------|
| `init` | Interactive config creation |
| `test` | Dry run: SSH to all devices, don't upload |
| `run` | One-shot: collect and upload all devices |
| `start` | Foreground daemon on cron schedule (`-d` to background) |
| `stop` / `status` | Manage the running daemon |
| `install-service` / `uninstall-service` | systemd/launchd auto-start |
| `demo` | Fake device backups, no SSH needed |
| `uninstall` | Remove agent and local data (cloud backups stay) |

## Docker

```bash
cp config.example.yaml config.yaml   # edit it
docker compose up -d
```

On Linux, uncomment `network_mode: host` in `docker-compose.yml` if your
devices aren't reachable from the container network.

## Notes

- Failed uploads are queued in `~/.configstash/pending/` and retried on the
  next run — safe across API downtime.
- All local state lives in `~/.configstash/` (mode `700`).
- Always use an `https://` API URL in production — the agent warns otherwise.

## License

[MIT](LICENSE)
