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)
• 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.1.12_amd64.deb

# Install the package
sudo dpkg -i gentility-agent_1.1.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.

Configuration File

The only required configuration is your access token:

# /etc/gentility.yaml
GENTILITY_TOKEN="gnt_1234567890abcdef"

Get your access token from your Gentility AI dashboard.

Advanced Configuration Options

The configuration file supports additional security and operational settings:

# /etc/gentility.yaml

# Required: Your access token
GENTILITY_TOKEN="gnt_1234567890abcdef"

# Optional: Server connection settings
SERVER_URL="wss://ws.gentility.ai"  # Default server
NICKNAME="staging-app-03"                 # Agent nickname (default: hostname)
ENVIRONMENT="prod"                   # Environment: prod or staging
DEBUG="false"                        # Enable debug logging

# Security settings
SECURITY_MODE="none"                 # Security mode: none, password, totp
SECURITY_PASSWORD="mypassword"       # Password for password mode
SECURITY_TOTP_SECRET="ABC123..."     # TOTP secret for TOTP mode
SECURITY_UNLOCK_TIMEOUT="1800"   # Security timeout in seconds (30 minutes)
SECURITY_EXTENDABLE="true"           # Allow extending security sessions

# Promiscuous mode (allows config sharing)
PROMISCUOUS_ENABLED="true"           # Enable promiscuous mode
PROMISCUOUS_AUTH_MODE="password"     # Auth mode for promiscuous operations

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 setup <token>             # Initial setup
gentility security <mode> [value]   # Configure security
gentility test-totp <code>          # Test TOTP validation
gentility promiscuous <action>      # Configure promiscuous mode

# 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

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

For Developers

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