oqto-setup - SKILL.md Agent Skill

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

Component	Required For	Check Command
Rust	Building	`cargo --version`
Bun	Frontend	`bun --version`
Git	Clone repos	`git --version`
Docker/Podman	Container mode	`docker --version` or `podman --version`
ttyd	Web terminal	`ttyd --version`
pi	Main chat	`pi --version`

Required Repositories

Core Platform

Repository	Purpose	Installation
oqto	Main platform (this repo)	`git clone https://github.com/byteowlz/oqto`

Backend Services

Repository	Purpose	Installation
hstry	Chat history storage (gRPC + SQLite)	`cargo install --git https://github.com/byteowlz/hstry`
mmry	Memory system with semantic search	`cargo install --git https://github.com/byteowlz/mmry`
trx	Issue and task tracking	`cargo install --git https://github.com/byteowlz/trx`

Agent Runtime

Repository	Purpose	Installation
pi	Main chat/LLM interface	`cargo install --git https://github.com/byteowlz/pi`
agntz	Agent toolkit (memory, issues, mail)	`cargo install --git https://github.com/byteowlz/agntz`

Voice Mode (Optional)

Repository	Purpose	Installation
eaRS	Speech-to-text (STT) service	`cargo install --git https://github.com/byteowlz/ears`
kokorox	Text-to-speech (TTS) service	`cargo install --git https://github.com/byteowlz/kokorox`

Search Service (Optional)

Repository	Purpose	Installation
SearXNG	Self-hosted meta-search engine	See SearXNG Setup below

Cross-Repo Tools

Repository	Purpose	Installation
sx	External search via SearXNG	`go install https://github.com/byteowlz/sx`
scrpr	Get website content	`go install https://github.com/byteowlz/scrpr`

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

Mode	Description	Use Case
Single-user	Shared workspace, no auth	Personal laptops, single dev
Multi-user	Isolated workspaces, auth required	Teams, shared servers

Backend Modes

Mode	Description	Requirements
Local	Native processes via oqto-runner	opencode, fileserver, ttyd, pi binaries
Container	Docker/Podman isolation	Docker/Podman runtime, oqto-dev image

Note: macOS multi-user requires container mode.

Deployment Modes

Mode	Auth	TLS	Use Case
Development	Dev users, no JWT	HTTP only	Local development
Production	JWT + invite codes	HTTPS via Caddy	Servers, production

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 -f deploy/docker/Dockerfile -t oqto:latest .

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

Variable	Default	Description
`OQTO_USER_MODE`	single	single or multi
`OQTO_BACKEND_MODE`	local	local or container
`OQTO_CONTAINER_RUNTIME`	auto	docker, podman, or auto
`OQTO_INSTALL_DEPS`	yes	Install dependencies
`OQTO_INSTALL_SERVICE`	yes	Install systemd/launchd service
`OQTO_INSTALL_AGENT_TOOLS`	yes	Install agntz, mmry, trx, mailz, sx
`OQTO_DEV_MODE`	-	true for dev mode, false for production
`OQTO_LOG_LEVEL`	info	error, warn, info, debug, trace
`OQTO_SETUP_CADDY`	-	yes to install Caddy reverse proxy
`OQTO_DOMAIN`	-	Domain for HTTPS
`OQTO_HARDEN_SERVER`	-	yes to enable server hardening (Linux)

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

File	Purpose
`~/.config/oqto/config.toml`	Main server config
`~/.config/opencode/opencode.json`	OpenCode agent config
`frontend/.env.local`	Frontend environment
`/etc/caddy/Caddyfile`	Reverse proxy config (if using Caddy)

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

Scenario	Method
First-time setup, development	`./setup.sh` (interactive)
CI/CD automation	`./setup.sh --non-interactive`
Production server with hardening	`OQTO_DEV_MODE=false ./setup.sh`
Multi-server deployment	Ansible playbook
Container-only deployment	Manual Docker setup

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

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