Agent Overview
The jokowipe agent is a lightweight, single-binary process that runs on your database server. It is the execution layer of jokowipe.id — it performs the actual backup operations locally and reports results to the control plane API.
Architecture
What the Agent Does
- Registers with the jokowipe.id API using an agent token
- Long-polls the API for pending backup jobs
- Executes backup commands (pg_dump, mysqldump, mongodump, etc.)
- Compresses the backup output (gzip by default)
- Uploads the compressed backup to your configured storage target
- Verifies the upload with a SHA-256 checksum
- Reports job status, metrics, and logs to the API
- Cleans up expired backup files from storage (based on retention policy)
Key Properties
| Property | Value |
|---|---|
| Language | Go (single static binary) |
| Binary size | ~15 MB |
| Memory footprint | ~20 MB idle, ~50-100 MB during backup |
| CPU usage | Low idle, moderate during backup/upload |
| Network | Outbound HTTPS only (no inbound ports needed) |
| Auth | JWT agent token (short-lived, auto-refreshed) |
| OS Support | Linux (amd64, arm64), macOS, Windows |
Security Model
- The agent communicates outbound only over HTTPS (port 443)
- No inbound firewall rules are required
- Agent tokens are JWTs signed by the API and auto-refreshed before expiry
- Storage credentials are delivered to the agent over encrypted channels and stored in memory only (not written to disk)
- The agent runs as a non-root user (recommended: dedicated
jokowipesystem user)
Agent vs. API Key
| Agent Token | API Key | |
|---|---|---|
| Purpose | Authenticate the agent process | Authenticate API calls from code/scripts |
| Scope | Execute backup jobs assigned to this agent | Full API access based on user role |
| Rotation | Auto-refreshed by the agent | Manual rotation required |
| Where used | agent.yaml config file | HTTP Authorization header |
Supported Platforms
| Platform | Architectures | Package Formats |
|---|---|---|
| Linux | amd64, arm64, armv7 | Binary, deb, rpm, Docker |
| macOS | amd64, arm64 (Apple Silicon) | Binary, Homebrew |
| Windows | amd64 | Binary, MSI, Chocolatey |