nannyagent/docs/INSTALLATION.md

NannyAgent Installation Guide

Quick Install

One-Line Install (Recommended)

After uploading install.sh to your website:

curl -fsSL https://your-domain.com/install.sh | sudo bash

Or with wget:

wget -qO- https://your-domain.com/install.sh | sudo bash

Two-Step Install (More Secure)

Download and inspect the installer first:

# Download the installer
curl -fsSL https://your-domain.com/install.sh -o install.sh

# Inspect the script (recommended!)
less install.sh

# Make it executable
chmod +x install.sh

# Run the installer
sudo ./install.sh

Installation from GitHub

If you're hosting on GitHub:

curl -fsSL https://raw.githubusercontent.com/yourusername/nannyagent/main/install.sh | sudo bash

System Requirements

Before installing, ensure your system meets these requirements:

Operating System

• ✅ Linux (any distribution)
• ❌ Windows (not supported)
• ❌ macOS (not supported)
• ❌ Containers/Docker (not supported)
• ❌ LXC (not supported)

Architecture

• ✅ amd64 (x86_64)
• ✅ arm64 (aarch64)
• ❌ i386/i686 (32-bit not supported)
• ❌ Other architectures (not supported)

Kernel Version

• ✅ Linux kernel 5.x or higher
• ❌ Linux kernel 4.x or lower (not supported)

Check your kernel version:

uname -r
# Should show 5.x.x or higher

Privileges

• Must have root/sudo access
• Will create system directories:
  • /usr/local/bin/nannyagent (binary)
  • /etc/nannyagent (configuration)
  • /var/lib/nannyagent (data directory)

Network

• Connectivity to Supabase backend required
• HTTPS access to your Supabase project URL
• No proxy support at this time

What the Installer Does

The installer performs these steps automatically:

1. ✅ System Checks

   • Verifies root privileges
   • Detects OS and architecture
   • Checks kernel version (5.x+)
   • Detects container environments
   • Checks for existing installations

2. ✅ Dependency Installation

   • Installs bpftrace (eBPF tracing tool)
   • Installs bpfcc-tools (BCC toolkit)
   • Installs kernel headers if needed
   • Uses your system's package manager (apt/dnf/yum)

3. ✅ Build & Install

   • Verifies Go installation (required for building)
   • Compiles the nannyagent binary
   • Tests connectivity to Supabase
   • Installs binary to /usr/local/bin

4. ✅ Configuration

   • Creates /etc/nannyagent/config.env
   • Creates /var/lib/nannyagent data directory
   • Sets proper permissions (secure)
   • Creates installation lock file

Installation Exit Codes

The installer exits with specific codes for different scenarios:

Exit Code	Meaning	Resolution
0	Success	Installation completed
1	Not root	Run with sudo
2	Unsupported OS	Use Linux
3	Unsupported architecture	Use amd64 or arm64
4	Container detected	Install on bare metal or VM
5	Kernel too old	Upgrade to kernel 5.x+
6	Existing installation	Remove /var/lib/nannyagent first
7	eBPF tools failed	Check package manager and repos
8	Go not installed	Install Go from golang.org
9	Build failed	Check Go installation and dependencies
10	Directory creation failed	Check permissions
11	Binary installation failed	Check disk space and permissions

Post-Installation

After successful installation:

1. Configure Supabase URL

Edit the configuration file:

sudo nano /etc/nannyagent/config.env

Set your Supabase project URL:

SUPABASE_PROJECT_URL=https://your-project.supabase.co
TOKEN_PATH=/var/lib/nannyagent/token.json
DEBUG=false

2. Test the Installation

Check version (no sudo needed):

nannyagent --version

Show help (no sudo needed):

nannyagent --help

3. Run the Agent

Start the agent (requires sudo):

sudo nannyagent

On first run, you'll see authentication instructions:

Visit: https://your-app.com/device-auth
Enter code: ABCD-1234

Uninstallation

To remove NannyAgent:

# Remove binary
sudo rm /usr/local/bin/nannyagent

# Remove configuration
sudo rm -rf /etc/nannyagent

# Remove data directory (includes authentication tokens)
sudo rm -rf /var/lib/nannyagent

Troubleshooting

"Kernel version X.X is not supported"

Your kernel is too old. Check current version:

uname -r

Options:

1. Upgrade your kernel to 5.x or higher
2. Use a different system with a newer kernel
3. Check your distribution's documentation for kernel upgrades

"Another instance may already be installed"

The installer detected an existing installation. Options:

Option 1: Remove the existing installation

sudo rm -rf /var/lib/nannyagent

Option 2: Check if it's actually running

ps aux | grep nannyagent

If running, stop it first, then remove the data directory.

"Cannot connect to Supabase"

This is a warning, not an error. The installation will complete, but the agent won't work without connectivity.

Check:

1. Is SUPABASE_PROJECT_URL set correctly?

   cat /etc/nannyagent/config.env
   

2. Can you reach the URL?

   curl -I https://your-project.supabase.co
   

3. Check firewall rules:

   sudo iptables -L -n | grep -i drop
   

"Go is not installed"

The installer requires Go to build the binary. Install Go:

Ubuntu/Debian:

sudo apt update
sudo apt install golang-go

RHEL/CentOS/Fedora:

sudo dnf install golang

Or download from: https://golang.org/dl/

"eBPF tools installation failed"

Check your package repositories:

Ubuntu/Debian:

sudo apt update
sudo apt install bpfcc-tools bpftrace

RHEL/Fedora:

sudo dnf install bcc-tools bpftrace

Security Considerations

Permissions

The installer creates directories with restricted permissions:

• /etc/nannyagent - 755 (readable by all, writable by root)
• /etc/nannyagent/config.env - 600 (only root can read/write)
• /var/lib/nannyagent - 700 (only root can access)

Authentication Tokens

Authentication tokens are stored securely in:

/var/lib/nannyagent/token.json

Only root can access this file (permissions: 600).

Network Communication

All communication with Supabase uses HTTPS (TLS encrypted).

Manual Installation (Alternative)

If you prefer manual installation:

# 1. Clone repository
git clone https://github.com/yourusername/nannyagent.git
cd nannyagent

# 2. Install eBPF tools (Ubuntu/Debian)
sudo apt update
sudo apt install bpfcc-tools bpftrace linux-headers-$(uname -r)

# 3. Build binary
go mod tidy
CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -ldflags '-w -s' -o nannyagent .

# 4. Install
sudo cp nannyagent /usr/local/bin/
sudo chmod 755 /usr/local/bin/nannyagent

# 5. Create directories
sudo mkdir -p /etc/nannyagent
sudo mkdir -p /var/lib/nannyagent
sudo chmod 700 /var/lib/nannyagent

# 6. Create configuration
sudo cat > /etc/nannyagent/config.env <<EOF
SUPABASE_PROJECT_URL=https://your-project.supabase.co
TOKEN_PATH=/var/lib/nannyagent/token.json
DEBUG=false
EOF

sudo chmod 600 /etc/nannyagent/config.env

Support

For issues or questions:

• GitHub Issues: https://github.com/yourusername/nannyagent/issues
• Documentation: https://github.com/yourusername/nannyagent/docs