Linux Setup

Overview

Linux is YeePilot's primary platform and supports the full feature set, including kernel namespace sandboxing for command isolation. This guide covers installation, credential storage, sandbox configuration, and distribution-specific notes.

Supported Distributions

YeePilot runs on most modern Linux distributions:

Both amd64 (x86_64) and arm64 (aarch64) architectures are supported with native binaries.

Installation

Quick Install (Recommended)

The install script detects your architecture and installs the latest release:

curl -fsSL https://yee.to/install.sh | bash

This will:

1. Detect your OS and architecture (amd64 or arm64).
2. Download the latest YeePilot binary.
3. Verify the download checksum.
4. Install the binary to /usr/local/bin/yeepilot.
5. Set the correct file permissions.

After installation, verify it works:

yeepilot version

Manual Installation

If you prefer to install manually:

1. Download the correct archive from the releases page (opens in new tab):

   • yeepilot-linux-amd64.tar.gz for x86_64 systems
   • yeepilot-linux-arm64.tar.gz for ARM64 systems

2. Extract and install:

tar xzf yeepilot-linux-amd64.tar.gz
sudo mv yeepilot /usr/local/bin/
sudo chmod +x /usr/local/bin/yeepilot

3. Verify the installation:

yeepilot version

Initial Setup

Run the interactive setup to configure your AI provider and preferences:

yeepilot setup

This creates your configuration file at ~/.yeepilot/config.yaml and prompts you to configure your AI provider and API key.

Credential Storage

YeePilot stores API keys and authentication tokens in your system's secret service for security.

GNOME Keyring (Recommended)

Most desktop Linux distributions include GNOME Keyring. YeePilot uses the secret-tool command to interact with it.

Install secret-tool if missing:

# Ubuntu / Debian
sudo apt install libsecret-tools
 
# Fedora / CentOS
sudo dnf install libsecret
 
# Arch Linux
sudo pacman -S libsecret

Verify it is working:

secret-tool --version

Headless Servers

On headless servers without a desktop environment or keyring daemon, YeePilot automatically falls back to an encrypted JSON file at ~/.yeepilot/credentials.json. This file is created with restricted permissions (0600).

If you want to use GNOME Keyring on a headless server, you can start the keyring daemon manually:

eval $(dbus-launch --sh-syntax)
eval $(gnome-keyring-daemon --start --components=secrets)

Sandbox Features

Linux provides the most comprehensive sandbox environment through kernel namespaces. When sandbox namespaces are enabled, every command YeePilot executes runs in an isolated environment.

Namespace Isolation

YeePilot uses four Linux namespace types:

Enabling Namespaces

Namespaces are enabled by default on Linux. Verify your configuration:

# ~/.yeepilot/config.yaml
sandbox:
  enabled: true
  use_namespaces: true

Kernel Requirements

User namespaces must be enabled in your kernel. Most modern distributions enable them by default. Check with:

cat /proc/sys/kernel/unprivileged_userns_clone

If the output is 0, enable it:

# Temporary (until reboot)
sudo sysctl kernel.unprivileged_userns_clone=1
 
# Permanent
echo 'kernel.unprivileged_userns_clone=1' | sudo tee /etc/sysctl.d/99-yeepilot.conf
sudo sysctl --system

Note: Some hardened kernels (e.g., certain CentOS/RHEL configurations) disable user namespaces by default. If you cannot enable them, set sandbox.use_namespaces: false to fall back to process-level resource limits.

Audit Logging

YeePilot's audit log provides a tamper-evident record of all commands executed. Each log entry is signed with HMAC-SHA256 and linked in a hash chain, making it possible to detect any modifications to the log history.

The audit log is stored at ~/.yeepilot/audit.log by default. To change the location:

security:
  audit_log_path: "/var/log/yeepilot/audit.log"

Make sure the directory exists and the user has write permissions:

sudo mkdir -p /var/log/yeepilot
sudo chown $(whoami) /var/log/yeepilot

Distribution-Specific Notes

Ubuntu / Debian

# Install dependencies
sudo apt update
sudo apt install libsecret-tools curl
 
# Install YeePilot
curl -fsSL https://yee.to/install.sh | bash

Fedora / CentOS / RHEL

# Install dependencies
sudo dnf install libsecret curl
 
# Install YeePilot
curl -fsSL https://yee.to/install.sh | bash

On CentOS 8 or RHEL 8, you may need to enable user namespaces:

sudo sysctl kernel.unprivileged_userns_clone=1

Arch Linux

# Install dependencies
sudo pacman -S libsecret curl
 
# Install YeePilot
curl -fsSL https://yee.to/install.sh | bash

Alpine Linux

Alpine uses musl libc. YeePilot provides statically linked binaries that work on Alpine without additional dependencies.

# Install curl if needed
apk add curl
 
# Install YeePilot
curl -fsSL https://yee.to/install.sh | bash

Note: GNOME Keyring is not typically available on Alpine. YeePilot will use the JSON file fallback for credential storage.

Updating

Update to the latest version:

yeepilot update

Or reinstall via the install script:

curl -fsSL https://yee.to/install.sh | bash

Uninstalling

Remove YeePilot and all its data:

yeepilot uninstall --all

Or remove only the binary while keeping your configuration:

yeepilot uninstall --binary-only

For a manual removal:

sudo rm /usr/local/bin/yeepilot
rm -rf ~/.yeepilot