Codakey
Play
← Back to safepilot

How to Deploy & Use safepilot

SafePilot Deployment and Usage Guide

This guide provides comprehensive instructions for deploying and using SafePilot, an AI assistant designed to execute real work safely.

1. Prerequisites

Before deploying SafePilot, ensure you have the following installed and configured:

  • Rust Toolchain: SafePilot is built with Rust. Install rustup by following the instructions on rustup.rs.
  • Docker and Docker Compose: For containerized deployment, Docker and Docker Compose are highly recommended.
  • Telegram Bot Token: Obtain a bot token by talking to BotFather on Telegram.
  • LLM Provider API Key: SafePilot supports Anthropic and OpenAI. You will need an API key for your chosen provider.
  • SQLite: SafePilot uses SQLite for persistent storage. No separate installation is typically needed as it's embedded, but ensure your environment can handle SQLite database files.

2. Installation

  1. Clone the Repository:

    git clone https://github.com/3DCF-Labs/safepilot.git
cd safepilot

  2. Build (if not using Docker):

    cargo build --release

    The executable will be located at target/release/safepilot.

3. Configuration

SafePilot is configured primarily through environment variables. It's recommended to use a .env file for local development or Docker Compose secrets for production.

Minimum Required Configuration:

  • BOT_TOKEN: Your Telegram bot token.
  • ALLOWED_USER_ID: Your Telegram user ID (numeric) to bootstrap as the owner. This user will have full access.
  • LLM_MODE: direct or agent. direct is recommended for initial setup.
  • LLM_PROVIDER: anthropic or openai.
  • ANTHROPIC_API_KEY or OPENAI_API_KEY: Your API key for the chosen LLM provider. Use ANTHROPIC_API_KEY_FILE or OPENAI_API_KEY_FILE for production with file-based secrets.

Recommended Security Configuration:

  • STRICT_SECRET_FILE_PERMS=1: Enforces chmod 600 on secret files.
  • ORCH_MASTER_KEY_FILE: Path to a file containing your master encryption key for sensitive DB fields. If unset, a key will be auto-generated at ~/.tg-orch/keys/master.key.
  • AGENT_ENABLE_WRITE_TOOLS=0: Disable agent's write capabilities by default.
  • AGENT_ENABLE_BROWSER_TOOL=0: Disable agent's browser tool by default.

File-based Secrets (Recommended for Production):

Instead of directly setting *_KEY environment variables, use *_KEY_FILE to point to a file containing the secret. Example:

BOT_TOKEN_FILE=/run/secrets/telegram_bot_token
ANTHROPIC_API_KEY_FILE=/run/secrets/anthropic_api_key
ORCH_MASTER_KEY_FILE=/run/secrets/master_encryption_key

Ensure these files have chmod 600 permissions.

Other Important Configuration Variables:

  • DATA_DIR: Directory for SQLite database and other persistent data (default: ./data).
  • LOG_DIR: Directory for logs (default: ./logs).
  • WORKSPACE_BASE_DIR: Base directory for workspace execution (default: ./workspaces).
  • LLM_HTTP_TIMEOUT_SECS: Timeout for LLM HTTP requests (default: 60).
  • ANTHROPIC_MODEL / OPENAI_MODEL: Specify the LLM model to use.
  • ALLOWED_SHELL_COMMANDS: Comma-separated list of bare binary names allowed for shell actions (e.g., git,ls,cat).
  • UNSAFE_SHELL_COMMANDS: Comma-separated list of bare binary names allowed for shell actions that require approval.
  • TG_ORCH_SAFE_PATH: Minimal PATH for subprocesses.
  • TG_ORCH_DANGEROUS_SANDBOX_ENABLED: Enable Linux sandboxing for dangerous jobs.

4. Build & Run

Local Development (without Docker)

  1. Create a .env file:

    BOT_TOKEN=YOUR_TELEGRAM_BOT_TOKEN
ALLOWED_USER_ID=YOUR_TELEGRAM_USER_ID
LLM_MODE=direct
LLM_PROVIDER=anthropic # or openai
ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY # or OPENAI_API_KEY
DATA_DIR=./data
LOG_DIR=./logs
WORKSPACE_BASE_DIR=./workspaces

  2. Run SafePilot:

    cargo run --release

Production with Docker Compose (Recommended)

The provided docker-compose.yml is configured for production use, leveraging secrets and persistent volumes.

  1. Prepare Secret Files: Create files for your secrets (e.g., telegram_bot_token.txt, anthropic_api_key.txt, master_encryption_key.txt).

    echo "YOUR_TELEGRAM_BOT_TOKEN" > telegram_bot_token.txt
echo "YOUR_ANTHROPIC_API_KEY" > anthropic_api_key.txt
# Generate a random 32-byte key for ORCH_MASTER_KEY_FILE
openssl rand -base64 32 > master_encryption_key.txt

    Ensure these files have chmod 600 permissions.

  2. Edit docker-compose.yml:

    • Uncomment and configure the secrets section to point to your secret files.
    • Adjust environment variables as needed, especially LLM_MODE, LLM_PROVIDER, ALLOWED_USER_ID, and ORCH_MASTER_KEY_FILE.
    • Ensure DATA_DIR and LOG_DIR are mapped to persistent volumes.

    Example docker-compose.yml snippet:

    version: '3.8'
services:
  safepilot:
    image: 3dcf/safepilot:latest
    container_name: safepilot
    restart: unless-stopped
    environment:
      # Basic configuration
      ALLOWED_USER_ID: "YOUR_TELEGRAM_USER_ID"
      LLM_MODE: "direct"
      LLM_PROVIDER: "anthropic" # or openai
      # File-based secrets
      BOT_TOKEN_FILE: "/run/secrets/telegram_bot_token"
      ANTHROPIC_API_KEY_FILE: "/run/secrets/anthropic_api_key" # or OPENAI_API_KEY_FILE
      ORCH_MASTER_KEY_FILE: "/run/secrets/master_encryption_key"
      # Security recommendations
      STRICT_SECRET_FILE_PERMS: "1"
      AGENT_ENABLE_WRITE_TOOLS: "0"
      AGENT_ENABLE_BROWSER_TOOL: "0"
      # Data directories
      DATA_DIR: "/app/data"
      LOG_DIR: "/app/logs"
      WORKSPACE_BASE_DIR: "/app/workspaces"
      # Optional: 3DCF compression
      # ENABLE_3DCF_COMPRESSION: "1"
    volumes:
      - safepilot_data:/app/data
      - safepilot_logs:/app/logs
      - safepilot_workspaces:/app/workspaces
    secrets:
      - telegram_bot_token
      - anthropic_api_key # or openai_api_key
      - master_encryption_key
secrets:
  telegram_bot_token:
    file: ./telegram_bot_token.txt
  anthropic_api_key:
    file: ./anthropic_api_key.txt
  master_encryption_key:
    file: ./master_encryption_key.txt
volumes:
  safepilot_data:
  safepilot_logs:
  safepilot_workspaces:

  3. Deploy with Docker Compose:

    docker compose up -d

5. Deployment

SafePilot is designed for self-hosted deployment. The recommended approach is using Docker Compose as detailed above.

Key considerations for production deployment:

  • Security Hardening: Review docs/hardening.md and docs/docker.md for host and Docker hardening best practices.
  • Secrets Management: Always use file-based secrets (*_FILE environment variables) and integrate with your secret management solution (e.g., Docker secrets, Kubernetes secrets, Vault).
  • Persistent Storage: Ensure DATA_DIR, LOG_DIR, and WORKSPACE_BASE_DIR are mapped to persistent volumes to avoid data loss on container restarts.
  • Resource Allocation: Monitor CPU, memory, and disk usage and allocate sufficient resources. LLM interactions can be memory-intensive.
  • Monitoring and Logging: Set up monitoring for the SafePilot container and review logs regularly for issues.

6. Troubleshooting

  • Bot Not Responding:

    • Check BOT_TOKEN and ALLOWED_USER_ID are correctly set.
    • Verify the bot token is active with BotFather.
    • Check SafePilot logs for connection errors to Telegram.
    • Ensure your server's network allows outbound connections to Telegram API.

  • LLM API Errors:

    • Verify ANTHROPIC_API_KEY or OPENAI_API_KEY is correct and has access to the specified model.
    • Check SafePilot logs for LLM provider error messages.
    • Ensure your server's network allows outbound connections to Anthropic/OpenAI APIs.
    • Check your LLM provider's usage limits and billing.

  • "Permission Denied" Errors:

    • If running without Docker, ensure the user running SafePilot has write permissions to DATA_DIR, LOG_DIR, and WORKSPACE_BASE_DIR.
    • If using Docker, verify volume mounts are correctly configured and the container user has permissions within the mounted volumes.
    • For file-based secrets, ensure the secret files are readable by the SafePilot process (e.g., chmod 600).

  • Tasks Blocked / Not Executing:

    • In LLM_MODE=agent, risky tasks require approval. Check Telegram for approval prompts (inline buttons or natural language "yes").
    • Review the docs/security-model.md for understanding task classification and approval workflows.
    • Check the SafePilot logs for policy enforcement messages.

  • shell command failures:

    • Ensure the command is in the ALLOWED_SHELL_COMMANDS or UNSAFE_SHELL_COMMANDS list.
    • Remember that bash and sh are explicitly refused by default for safety. Use specific binaries like git, ls, cat.
    • Subprocesses run with a cleared environment and minimal PATH. Ensure necessary binaries are available in the TG_ORCH_SAFE_PATH or fully qualified.

  • SSRF Protection Blocking fetch:

    • The fetch tool blocks private/loopback/link-local/metadata IPs by default. If you need to access internal resources, you might need to adjust network policies (refer to security documentation, but proceed with caution).

  • Database Encryption Issues:

    • If ORCH_MASTER_KEY_FILE is used, ensure the file exists and contains the correct key.
    • Losing the master key will result in unrecoverable encrypted data. Back up your master key securely.

For further debugging, increase the logging level by setting RUST_LOG=debug or RUST_LOG=trace in your environment variables.

← Project overviewView alternatives to safepilot →