Petacomm
Overview
Petacomm is a suite of Linux server and user tools designed for developers and system administrators. This documentation covers three primary tools:
- Petacomm Easy — AI-powered Linux server management via natural language
(
peta -r) - GateBell — Real-time SSH gateway monitor with instant alerting
- RouteChecker — Network route analysis and diagnostics tool
All tools are open source under the GPL-3.0 license and ship as single binaries with no runtime dependencies.
Prerequisites
Before installing any Petacomm tool, ensure your system meets the following requirements.
System requirements
| Requirement | Minimum | Notes |
|---|---|---|
| Linux kernel | 4.15+ | Ubuntu 18.04, Debian 10, RHEL 8 or newer |
| Architecture | amd64 / arm64 | Both architectures fully supported |
| RAM | 128 MB | All tools combined use <30 MB at idle |
| Disk | 50 MB | Binaries + default config + log rotation |
| Root / sudo | Required | For installation and service management |
Petacomm Easy — additional requirement
Petacomm Easy requires an Anthropic Claude API key to process natural language commands. You can obtain one at platform.claude.com.
peta configure --api-key).Quick Install
Install all Petacomm tools in a single command using the Easy installer script. The script auto-detects your distribution and installs the correct packages.
$ curl -fsSL https://repo.kotechsoft.com/easy.sh | sudo bash
✓ Distro detected: Ubuntu 24.04 LTS
✓ petacomm-easy 3.4.1 installed
✓ gatebell 1.0.3 installed
✓ All services enabled and running
After installation, configure your Claude API key and start all services:
$ sudo peta start --enable-all
✓ 6 tools active. Web UI: http://localhost:7474
Petacomm Easy
Petacomm Easy is an AI-driven Linux server management tool. Instead of memorizing commands, you describe what
you want in plain English and peta -r translates your intent into the correct Linux command —
showing it to you before execution.
Every command generated is logged in an append-only audit file. Any action can be reversed with
peta undo.
Installing Petacomm Easy
Via apt (Debian / Ubuntu)
-o /usr/share/keyrings/petacomm.gpg
$ echo "deb [signed-by=/usr/share/keyrings/petacomm.gpg] https://apt.petacomm.io stable main" \
| sudo tee /etc/apt/sources.list.d/petacomm.list
$ sudo apt update && sudo apt install -y petacomm-easy
Via one-line installer
Via pacman (Arch Linux)
Configuration
Configuration is stored at /etc/petacomm/easy.conf. You can edit it directly or use the
peta configure command.
Set your Claude API key
# Or set as environment variable
$ export PETACOMM_API_KEY=sk-ant-xxxxxxxxxxxxxxxx
Configuration file reference
api_key = sk-ant-xxxxxxxxxxxxxxxx
# Claude model to use (claude-sonnet recommended)
model = claude-sonnet-4-20250514
# Require explicit confirmation before executing commands
confirm_before_exec = true
# Audit log path
audit_log = /var/log/petacomm/audit.log
# Block dangerous commands even with AI approval
block_destructive = true
# Max tokens for AI response
max_tokens = 1024
CLI Usage
Basic syntax
peta --run "your natural language request here"
Flags
| Flag | Type | Description |
|---|---|---|
| -r, --run | string | Natural language command to execute |
| -y, --yes | bool | Skip confirmation prompt — execute immediately |
| --dry-run | bool | Show the generated command without executing |
| --undo | bool | Revert the last executed command |
| --history | bool | Show recent command history from audit log |
| --model | string | Override the Claude model for this request |
| --no-log | bool | Skip audit log for this command (not recommended) |
Examples
Disk management
AI Running: du -sh /* 2>/dev/null | sort -rh | head -20
→ Execute? [y/N]: y
18G /var/log
12G /home/deploy/.cache
8G /tmp
AI /var/log is large. Rotate nginx logs? [y/N]: y
✓ Freed 16.2 GB
Process management
AI Running: systemctl restart nginx && systemctl status nginx
→ Execute? [y/N]: y
✓ nginx restarted successfully — active (running) since 2s
Security inspection
AI Running: journalctl -u sshd --since "1 hour ago" | grep "Failed password"
→ Execute? [y/N]: y
Dry-run mode — see the command without executing
AI Would run: find /tmp -type f -mtime +30 -delete
[dry-run — no changes made]
Audit Log
Every command Petacomm Easy generates, approves, and executes is written to an append-only structured log at
/var/log/petacomm/audit.log.
Log format
{"ts":"2026-04-28T09:22:11Z","user":"deploy","request":"show disk usage","command":"du -sh /* 2>/dev/null | sort -rh | head -20","approved":true,"exit":0}
View recent history
$ peta --history --last 20
GateBell
GateBell is a real-time SSH gateway monitoring and alerting daemon. It watches every connection attempt, login and logout on your server and delivers alerts with under 2ms latency via Slack, Discord, email, or any webhook endpoint.
GateBell runs as a lightweight system daemon using ~4 MB of RAM. It integrates with PAM to intercept SSH events without requiring SSH configuration changes.
Installing GateBell
$ sudo apt install gatebell
# Start and enable on boot
$ sudo systemctl enable --now gatebell
✓ GateBell active — watching 3 interfaces
GateBell Configuration
Configuration file: /etc/gatebell/gatebell.conf
interfaces = *
# Auto-ban after N failed attempts within window_seconds
ban_threshold = 5
ban_window_sec = 60
ban_duration_min = 1440
# Geo-location lookup (uses local MaxMind DB)
geo_lookup = true
geo_db_path = /var/lib/gatebell/GeoLite2-City.mmdb
# Audit log
audit_log = /var/log/gatebell/events.log
log_format = json
Alert Channels
GateBell supports multiple notification channels. Configure one or more in
/etc/gatebell/alerts.conf.
Slack
enabled = true
webhook_url = https://hooks.slack.com/services/T.../B.../xxx
channel = #security
on_events = login,attempt,ban
enabled = true
smtp_host = smtp.example.com
smtp_port = 587
smtp_user = [email protected]
smtp_pass = your-password
to = [email protected]
on_events = ban,critical
Custom webhook
enabled = true
url = https://your-endpoint.example.com/gatebell
method = POST
on_events = *
Rule Engine
Define custom allow/deny rules in /etc/gatebell/rules.conf. Rules are evaluated in order; the
first match wins.
allow ip_range=192.168.1.0/24 silent=true
# Allow known admin IPs
allow ip=203.0.113.10 label="home-admin"
# Instantly ban TOR exit nodes
ban reputation=tor duration=permanent
# Alert on root login attempts from any unknown IP
alert user=root action=attempt channel=slack,email
Rule actions
| Action | Description |
|---|---|
| allow | Permit and optionally suppress alerts for matching connections |
| alert | Send notification without blocking the connection |
| ban | Add IP to firewall blocklist immediately |
| log | Write to audit log only, no alert |
GateBell REST API
GateBell exposes a local REST API on port 7475 by default. All endpoints require the API token
set in your config file.
Authentication
$ sudo gatebell config set api_token your-secret-token
Endpoints
| Method + Path | Description |
|---|---|
| GET /api/status | Daemon health, uptime, active interface count |
| GET /api/events | Recent events (paginated, filterable by type) |
| GET /api/bans | Current active IP ban list |
| POST /api/bans | Add an IP to the ban list manually |
| DELETE /api/bans/:ip | Remove an IP from the ban list |
| GET /api/rules | List all configured rules |
| POST /api/test-alert | Send a test notification to all configured channels |
RouteChecker
RouteChecker is a network route analysis and diagnostics tool. It provides real-time visibility into BGP route paths, latency hops, and network reachability — presented in a clear, readable interface without requiring deep networking expertise.
RouteChecker has a dedicated web interface and full documentation available at its own website.
RouteChecker — Quick Reference
What it does
- Route path analysis — trace the exact BGP path from source to destination
- Latency hop breakdown — per-hop RTT with geographic context
- Reachability checks — verify if a host or subnet is reachable from multiple vantage points
- AS path inspection — view autonomous system numbers along the route
- Historical route diff — compare current vs. previous route paths
Access
RouteChecker is available as a web application and API. Visit routechecker.co.uk to get started.
peta CLI Reference
The peta command is the unified CLI entry point for all Petacomm tools.
| Command | Description |
|---|---|
| peta -r "..." | Run a natural language command via Petacomm Easy |
| peta status | Show status of all running Petacomm services |
| peta start | Start one or all services (--all) |
| peta stop | Stop one or all services |
| peta restart | Restart one or all services |
| peta configure | Set configuration values interactively or via flags |
| peta undo | Revert the last Petacomm Easy command |
| peta --history | Show audit log of recent Easy commands |
| peta security scan | Run CVE dependency scan |
| peta security patch | Apply available security patches |
| peta harden | Apply CIS hardening profile (--profile cis-level2) |
| peta logs | Tail live logs for a specific service |
| peta update | Update all Petacomm tools to latest versions |
| peta version | Print installed versions of all components |
Environment Variables
| Variable | Default | Description |
|---|---|---|
| PETACOMM_API_KEY | — | Anthropic Claude API key for Petacomm Easy |
| PETACOMM_MODEL | claude-sonnet-4-20250514 | Claude model override |
| PETACOMM_CONFIRM | true | Set to false to skip confirmation prompts |
| PETACOMM_LOG_DIR | /var/log/petacomm | Override log directory path |
| GATEBELL_TOKEN | — | GateBell REST API authentication token |
| GATEBELL_PORT | 7475 | GateBell API listening port |