Gentility AI Agent

A lightweight daemon that connects your servers and computers to Gentility AI.

Features

• Simple and Auditable trust, but verify
• Local credential capability so your secrets stay with you
• Secure credential exchange using X25519 key exchange and AES-256-CBC encryption
• Database query execution (PostgreSQL and MySQL)
• File read/write operations (when enabled)
• Egress mode for reaching internal services on the agent's network (opt-in, default-deny SSRF policy)
• Lockable for ultimate peace of mind

Supported Platforms

• Linux AMD64 (x86_64) - Primary support with static binaries
• Linux ARM64 - Coming soon
• macOS (Intel and Apple Silicon) - Homebrew support

Tested on Ubuntu 20.04+, Debian 11+, CentOS 8+, and other modern Linux distributions. macOS 10.15+ supported via Homebrew.

Installation

Option 0: If you're in a hurry

Option 1: APT Repository (Recommended)

Add the Gentility AI package repository to your system:

# Add GPG key for package verification (modern method)
sudo mkdir -p /etc/apt/keyrings
curl -s https://packages.gentility.ai/gentility-packages.gpg | sudo tee /etc/apt/keyrings/gentility-packages.asc > /dev/null

# Add repository with signed-by specification
echo "deb [signed-by=/etc/apt/keyrings/gentility-packages.asc] https://packages.gentility.ai/debian/ stable main" | sudo tee /etc/apt/sources.list.d/gentility.list

# Update package list and install
sudo apt update
sudo apt install gentility-agent

Option 2: Direct DEB Package

Download and install the latest package directly:

# Download the latest package
wget https://github.com/gentility-ai/agent/releases/download/v1.1.1/gentility-agent_1.2.12_amd64.deb

# Install the package
sudo dpkg -i gentility-agent_1.2.12_amd64.deb

# Install any missing dependencies
sudo apt-get install -f

Option 3: Homebrew (macOS)

Install via the Gentility Homebrew tap:

brew tap gentility-ai/agent
brew install gentility-agent

Option 4: Build from Source

Build and install from the official source code:

# Install Crystal language (if not already installed)
curl -fsSL https://crystal-lang.org/install.sh | sudo bash

# Clone the source repository
git clone https://github.com/gentility-ai/agent.git
cd agent

# Install dependencies
shards install

# Build the binary
crystal build src/agent.cr --release --static -o gentility

# Install manually (optional)
sudo cp gentility /usr/local/bin/gentility
sudo chmod +x /usr/local/bin/gentility

Quick Start

After installation, configure the agent with your access token using the setup command:

# Quick setup (recommended) - Creates or updates configuration
gentility auth

The auth command will:

• Create a new config file if none exists
• Take you to Gentility to associate this installation with an account

How to run:

Start the service:

# Start and enable the service
sudo systemctl start gentility
sudo systemctl enable gentility

# Check status
sudo systemctl status gentility

# View real-time logs
sudo journalctl -u gentility-agent -f

Uninstallation

To completely remove the agent from your system:

# Stop and disable the service
sudo systemctl stop gentility
sudo systemctl disable gentility

# Remove the package
sudo apt remove gentility-agent

# Optional: Remove configuration and logs
sudo rm -rf /etc/gentility.yaml
sudo rm -rf /var/log/gentility-agent
sudo rm -rf /var/lib/gentility-agent

# Optional: Remove repository from sources
sudo rm /etc/apt/sources.list.d/gentility.list
sudo rm /etc/apt/keyrings/gentility-packages.asc

Configuration

The agent is configured through /etc/gentility.yaml. Under the hood it's a plain YAML file — most of the time you'll use gentility auth and the gentility security / gentility egress commands to manage it, but you can also edit it directly.

Configuration File

After running gentility auth, a minimal config looks like:

# /etc/gentility.yaml
machine_key: genkey-agent-...
nickname: staging-app-03
environment: production

Advanced Configuration Options

# /etc/gentility.yaml

# Required: machine key (written by `gentility auth`)
machine_key: genkey-agent-...

# Optional: server / identity
server_url: wss://ws.gentility.ai   # default: wss://ws.gentility.ai
nickname: staging-app-03             # default: hostname
environment: production              # prod / dev
debug: false                         # enable debug logging

# Security settings (managed by `gentility security …`)
security:
  mode: none                         # none, password, or totp
  password: mypassword               # for password mode
  totp_secret: ABC123...             # for totp mode (base32)
  unlock_timeout: 1800               # seconds
  extendable: true                   # extend session on activity
  promiscuous_enabled: true          # allow server to export security config
  promiscuous_auth_mode: password    # password or totp

# Egress settings (managed by `gentility egress …`)
egress:
  enabled: false                     # must be true to accept egress frames
  allow_loopback: false              # allow 127.0.0.0/8, ::1
  allow_private_networks: false      # allow RFC1918 / CGNAT / IPv6 ULA

Egress Mode (Server-Initiated Outbound Proxy)

Egress mode lets the Gentility server open outbound TCP connections through the agent — useful for reaching internal services (databases, dashboards, internal APIs) that only the agent's network can see. The server tunnels the bytes over the existing authenticated WebSocket; no inbound ports are opened on the agent host.

Egress is disabled by default — opt in with the gentility egress CLI:

# Enable egress, optionally allowing internal networks
sudo gentility egress enable --allow-private-networks

# Toggle loopback separately
sudo gentility egress set --allow-loopback

# Check current state
gentility egress status

# Turn it off again
sudo gentility egress disable

These commands write to the egress: section of /etc/gentility.yaml. You can also edit the file directly:

egress:
  enabled: true                  # required to accept any egress frame
  allow_loopback: false          # allow connecting to 127.0.0.0/8 (default: false)
  allow_private_networks: false  # allow RFC1918 / CGNAT / IPv6 ULA (default: false)

After either path, restart the agent to apply:

sudo systemctl restart gentility

Two-step approval (Tailscale-style). Setting enabled: true in the agent config does not by itself make the agent an active egress route. It only advertises the capability to the server. On first sighting, the server auto-creates a route stub for this machine in a disabled state. An admin then has to flip that route on from the Gentility UI before any traffic actually flows through the agent. This is deliberate: a compromised or misconfigured agent cannot silently turn itself into an egress route for the org. If you've enabled egress in config but traffic isn't routing, check the route's enable toggle on the machine's edit page in Gentility.

Default-deny safety net. Even with enabled: true, the agent's dialer rejects any destination that resolves to: loopback, link-local (including the cloud metadata address 169.254.169.254), IPv4/IPv6 multicast, broadcast, the 0.0.0.0/8 wildcard range, and — unless allow_private_networks: true — RFC1918, CGNAT (100.64.0.0/10), and IPv6 ULA. IPv4-mapped IPv6 addresses (::ffff:10.0.0.1) are unmapped before the policy check so they cannot be used to bypass it.

When to enable each toggle:

• Just enabled: true — agent can reach the public internet on behalf of the server, but every internal range is blocked. Safest starting point.
• + allow_private_networks: true — required if the whole point is to reach internal services on RFC1918 addresses (e.g. a Postgres on 10.0.0.5). Only enable if you trust the server-side authorization controls; this is the dangerous knob.
• + allow_loopback: true — required to reach services bound to 127.0.0.1 on the agent host itself. Most installs do not need this.

Operational notes:

• Egress streams are isolated per connection: a slow or stuck destination cannot stall the agent's heartbeats or other streams (the writer is bounded and a saturated stream is torn down with an io_error).
• Errors and stream lifecycle events are reported back to the server as egress.stream.error / egress.stream.close frames, so failures are visible in the server-side egress logs rather than silently hanging.
• The server side must be running with EGRESS_ENABLED=true for any egress traffic to actually flow; check with your Gentility administrator.

Service Management

The agent runs as a systemd service and can be managed with standard commands:

# Check service status
sudo systemctl status gentility

# Start/stop the service
sudo systemctl start gentility
sudo systemctl stop gentility
sudo systemctl restart gentility

# Enable/disable automatic startup
sudo systemctl enable gentility
sudo systemctl disable gentility

# View logs
sudo journalctl -u gentility -f
sudo journalctl -u gentility --since="1 hour ago"

Troubleshooting

Common Issues

Service won't start:

# Check configuration file
sudo cat /etc/gentility.yaml

# Check service logs
sudo journalctl -u gentility-agent --no-pager

Connection issues:

# Test connectivity (if server is reachable)
curl -I https://api.gentility.ai

# Check firewall (port 443 outbound should be open)
sudo ufw status

Authentication errors:

• Verify your GENTILITY_TOKEN is correct
• Check that the token hasn't expired
• Ensure the token has appropriate permissions

Log Locations

• Service logs: sudo journalctl -u gentility
• Application logs: /var/log/gentility/ (if configured)

Security

• The agent uses secure WebSocket connections (WSS) with TLS encryption
• All packages are cryptographically signed
• The agent runs with minimal privileges
• Configuration files are protected with appropriate permissions
• No sensitive data is stored in logs

Secure Credential Exchange (v1.1.0+)

The agent implements X25519 Elliptic Curve Diffie-Hellman (ECDH) key exchange for secure credential transmission:

How it works:

1. Key Generation: Agent generates an Ed25519 seed key during initial setup (ed25519_seed_key)
2. Connection: Agent derives X25519 keypair from seed and sends public key to server via connection parameters
3. Welcome: Server sends its X25519 public key in the welcome message (server_x25519_pubkey)
4. Shared Secret: Both parties independently derive the same shared secret using ECDH
5. Encryption: Server encrypts database credentials with AES-256-CBC using the shared secret
6. Transmission: Encrypted credentials are sent to agent for database queries

Security properties:

• Shared secret is never transmitted over the network
• Each agent has a unique seed key
• Credentials are encrypted at rest in the agent's config file
• TLS provides additional transport-layer protection

New Commands:

• store_credentials: Server stores encrypted credentials for a database target
• secure_psql_query: Execute PostgreSQL query using encrypted credentials
• secure_mysql_query: Execute MySQL query using encrypted credentials

Rate Limiting

The agent supports password and TOTP authentication with built-in rate limiting to prevent brute-force attacks.

After 5 failed authentication attempts, the agent enters lockout mode. Each failed attempt enforces an exponential backoff delay (30s, 60s, 120s, 240s).

See docs/SECURITY_RATE_LIMITING.md for details.

Support

For support, issues, or feature requests:

• GitHub Issues: Create an issue
• Documentation: docs.gentility.ai
• Email: support@gentility.ai

License

MIT License - see LICENSE file for details.

---

Command Line Interface

The gentility command provides several modes of operation:

Basic Usage

# Show help and available commands
gentility
gentility help

# Start the agent daemon
gentility run --token=YOUR_TOKEN_HERE
gentility start --token=YOUR_TOKEN_HERE --debug

Note: The agent no longer starts automatically. You must explicitly use the run or start command.

Setup Commands

sudo gentility auth

gentility run

Security Configuration

The agent supports multiple security modes to protect sensitive operations:

TOTP Authentication (Recommended)

# Enable TOTP with auto-generated secret
sudo gentility security totp

# Enable TOTP with custom secret
sudo gentility security totp ABC123DEF456GHI789

# Test your TOTP setup
sudo gentility test-totp 123456

TOTP setup will display a QR code that you can scan with any authenticator app (Google Authenticator, Authy, 1Password, etc.). The QR code is generated as ASCII art directly in your terminal.

Password Authentication

# Enable password security (prompts for password)
sudo gentility security password

# Enable password security with inline password
sudo gentility security password mySecretPassword123

Disable Security

# Disable all security (not recommended for production)
sudo gentility security none

Promiscuous Mode

Promiscuous mode allows the server to export and share security configuration across multiple agents:

# Enable promiscuous mode
sudo gentility promiscuous enable

# Disable promiscuous mode
sudo gentility promiscuous disable

# Check promiscuous mode status
sudo gentility promiscuous status

# Set promiscuous authentication mode
sudo gentility promiscuous auth password  # or 'totp'

Configuration Priority

Configuration is loaded in this order (later sources override earlier ones):

1. Default values (built into the application)
2. Configuration file (/etc/gentility.yaml)
3. Environment variables (GENTILITY_TOKEN, SERVER_URL, etc.)
4. Command line arguments (--token=, --debug)

Environment Variables

All configuration options can be set via environment variables:

export GENTILITY_TOKEN="your-token-here"
export SERVER_URL="wss://your-server.com"
export NICKNAME="my-custom-name"
export ENVIRONMENT="staging"
export DEBUG="true"

# Then start the agent
gentility run

Security Features

• Unlock timeout: Security sessions expire after 30 minutes by default
• Extendable sessions: Each command execution extends the security session
• Hard timeout: Sessions have an absolute maximum duration from first unlock
• Multiple auth modes: Support for both TOTP and password authentication
• Secure storage: All security settings are stored with 600 permissions in /etc/gentility.yaml
• QR code generation: TOTP setup includes ASCII QR codes for easy authenticator app configuration

Complete Command Reference

# Main Commands
gentility                           # Show help
gentility run [options]             # Start the agent daemon
gentility start [options]           # Alias for 'run'
gentility help                      # Show help

# Setup and Configuration
gentility auth                      # OAuth + machine key provisioning
gentility setup <token>             # Manual setup (advanced)
gentility security <mode> [value]   # Configure security
gentility test-totp <code>          # Test TOTP validation
gentility promiscuous <action>      # Configure promiscuous mode
gentility egress <action>           # Configure server-initiated egress

# Run Options
--token=<token>                     # Access token
--debug                             # Enable debug logging

# Security Modes
security totp [secret]              # TOTP authentication
security password [password]        # Password authentication
security none                       # No security
security clear-lockout              # Clear rate-limit lockout

# Promiscuous Actions
promiscuous enable                  # Enable promiscuous mode
promiscuous disable                 # Disable promiscuous mode
promiscuous status                  # Show status
promiscuous auth <mode>             # Set auth mode (password|totp)

# Egress Actions
egress status                               # Show current egress config
egress enable [flags]                       # Enable egress (with optional flags)
egress disable                              # Disable egress
egress set <flags>                          # Change allow flags only
#   --allow-loopback[=true|false]
#   --allow-private-networks[=true|false]

For Developers

If you're interested in contributing or building from source, see DEVELOPMENT.md for build instructions and development guidelines.