configstash-agent 0.1.0__tar.gz

configstash_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ConfigStash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

configstash_agent-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+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)

configstash_agent-0.1.0/README.md

@@ -0,0 +1,112 @@
+# 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)

configstash_agent-0.1.0/configstash_agent/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"