name: oqto-setup description: Guide users through Oqto platform setup, troubleshoot installation issues, and verify deployment configuration. Use when the user is installing Oqto, configuring the platform, or encountering setup-related problems.

Oqto Setup Guide for AI Agents

Oqto is a self-hosted AI agent workspace platform with multiple deployment modes and configuration options.

Quick Reference

Required Repositories

Core Platform

Backend Services

Agent Runtime

Voice Mode (Optional)

Search Service (Optional)

Cross-Repo Tools

Quick Install All Tools

# Install agntz first, then use it to install all tools
cargo install --git https://github.com/byteowlz/agntz

# Install all byteowlz tools via agntz
agntz tools install all

# Or install specific tools
agntz tools install mmry trx mailz sx

Setup Methods

1. Interactive Setup Script (Recommended)

./setup.sh

The script handles:

• OS detection and prerequisite installation
• User mode selection (single/multi)
• Backend mode selection (local/container)
• Dependency installation (Rust, Bun, shell tools)
• Building all components
• Configuration file generation
• Optional service installation

2. Non-Interactive Setup

# Development mode
OQTO_USER_MODE=single OQTO_BACKEND_MODE=local ./setup.sh --non-interactive

# Production mode with hardening
OQTO_DEV_MODE=false \
OQTO_HARDEN_SERVER=yes \
OQTO_SETUP_CADDY=yes \
OQTO_DOMAIN=oqto.example.com \
./setup.sh --non-interactive

3. Manual Setup

See SETUP.md for step-by-step manual installation.

Configuration Modes

User Modes

Backend Modes

Note: macOS multi-user requires container mode.

Deployment Modes

Common Setup Issues

Prerequisites Missing

# Check what's missing
./setup.sh  # Run interactively to install

# Or install manually:
# Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y

# Bun
curl -fsSL https://bun.sh/install | bash

# ttyd (Debian/Ubuntu)
sudo apt-get install -y ttyd

# ttyd (macOS)
brew install ttyd

Container Image Not Found

# Build the image
docker build -t oqto-dev:latest -f container/Dockerfile .

Port Already in Use

# Find process
lsof -i :8080  # Oqto backend port
lsof -i :3000  # Frontend port
lsof -i :8888  # SearXNG default port

# Kill or change ports in:
# ~/.config/oqto/config.toml (Oqto backend port)
# /etc/searxng/settings.yml (SearXNG port)

Permission Denied (systemd)

• User services: Use systemctl --user
• System services: Use sudo or run as root

Build Failures

# Clean and rebuild
cargo clean
cd backend && cargo build --release
cd fileserver && cargo build --release
cd frontend && bun install && bun run build

Environment Variables Reference

Post-Setup Verification

# Check binaries
which oqto && oqto --version
which fileserver && fileserver --version
which opencode && opencode --version
which ttyd && ttyd --version
which pi && pi --version

# Check config
cat ~/.config/oqto/config.toml

# Test backend (in one terminal)
oqto serve --local-mode

# Test frontend (in another terminal)
cd frontend && bun dev

# Access UI
open http://localhost:3000

Configuration Files

Service Management

Linux (systemd)

# User service
systemctl --user enable --now oqto
systemctl --user status oqto
journalctl --user -u oqto -f

# System service
sudo systemctl enable --now oqto
sudo systemctl status oqto
sudo journalctl -u oqto -f

macOS (launchd)

launchctl load ~/Library/LaunchAgents/ai.oqto.server.plist
launchctl list | grep oqto

Production Deployment Checklist

• Generated secure JWT secret (64+ characters)
• Created admin user with strong password
• Configured Caddy with proper domain
• Enabled HTTPS (Caddy auto-SSL)
• Set up firewall (UFW/firewalld)
• Configured fail2ban
• Hardened SSH (key auth only)
• Enabled automatic security updates
• Set correct file permissions
• Tested backup/restore procedures

When to Use Each Setup Method

Troubleshooting Commands

# Check logs
journalctl --user -u oqto -f  # User service
sudo journalctl -u oqto -f     # System service

# Check config validity
oqto config show

# Test runner connectivity
oqtoctl status

# Debug WebSocket
# In browser console:
localStorage.setItem("debug:ws", "1")

# Check port bindings
ss -tlnp | grep -E ':(8080|3000|8888)'

# Verify binary locations
ls -la ~/.cargo/bin/oqto*

SearXNG Setup

For use with the sx search tool, you can install SearXNG natively (no Docker required).

Option 1: Installation Script (Recommended)

git clone https://github.com/searxng/searxng.git
cd searxng
sudo -H ./utils/searxng.sh install all

Option 2: Manual Step-by-Step

Ubuntu/Debian:

# Install dependencies
sudo apt-get install -y python3-dev python3-babel python3-venv \
    uwsgi uwsgi-plugin-python3 git build-essential libxslt-dev \
    zlib1g-dev libffi-dev libssl-dev redis-server

# Create searxng user
sudo useradd --shell /bin/bash --system \
    --home-dir "/usr/local/searxng" \
    --comment 'Privacy-respecting metasearch engine' \
    searxng

sudo mkdir "/usr/local/searxng"
sudo chown -R "searxng:searxng" "/usr/local/searxng"

# Clone and install
sudo -H -u searxng -i
git clone "https://github.com/searxng/searxng" \
    "/usr/local/searxng/searxng-src"
cd /usr/local/searxng/searxng-src

# Create virtualenv and install
python3 -m venv /usr/local/searxng/searx-pyenv
source /usr/local/searxng/searx-pyenv/bin/activate
pip install -e .

Configure: Edit /etc/searxng/settings.yml:

server:
  port: 8888                    # Default: 8888 (change if conflicts with Oqto)
  bind_address: "127.0.0.1"     # Localhost only for security
  secret_key: "your-secret-key" # Change this!

search:
  formats:
    - html
    - json                    # REQUIRED: Enable API access for sx tool

Enable HTTP API: By default SearXNG only serves HTML. To use the API with the sx tool, you must add json to the search.formats list in /etc/searxng/settings.yml.

Service: SearXNG runs via uWSGI:

sudo systemctl start searxng
sudo systemctl enable searxng

Test API:

# Should return JSON results
curl 'http://localhost:8888/search?q=hello+world&format=json'

Configure sx tool:

# Set SearXNG URL for sx
export SEARXNG_URL=http://localhost:8888
# Or configure in sx config
sx config set searxng.url http://localhost:8888

Why SearXNG in 2026?

SearXNG remains the best FOSS meta-search engine:

• Aggregates results from 246+ search engines
• No tracking or profiling
• Active development and community
• Better than alternatives (Whoogle, LibreY) due to multi-engine aggregation

Getting Help

1. Check logs: journalctl --user -u oqto -f
2. Verify config: oqto config show
3. Check SETUP.md for detailed instructions
4. Check README.md for architecture overview
5. Review backend/examples/config.toml for all options