Quest AI Workbench - Guía Completa de Instalación y Despliegue
¿Qué es Quest?
Quest es un entorno de trabajo seguro para agentes de IA autocontenido, basado en FastAPI con React frontend. Conecta servicios externos (Gmail, Slack, GitHub, Airtable) mediante OAuth o claves API sin exponer datos sensibles al internet.
Arquitectura y componentes
- Servidor FastAPI: proceso único que sirve REST/WebSocket API y React frontend como static files
- Persistencia: SQLite database plus JSON files bajo data/
- Script runner: scripts LLMs ejecutan en ephemeral rootless Podman containers
- Seguridad por diseño: modo privado (sin internet) / modo público (sin acceso a recursos internos)
Requisitos reales (Debian 12/13)
| Software | Versión mínima | Propósito |
|---|---|---|
| Python | 3.11+ | Backend runtime |
| Node.js | 18+ | Frontend build (Vite) |
| npm | 9+ | Frontend package manager |
| Podman | 4+ | Rootless script-runner sandbox |
| uv | latest | Python package/venv manager |
Packages requeridos: git curl python3 python3-venv nodejs npm podman uidmap slirp4netns. uidmap y slirp4netns son obligatorios para rootless Podman.
1. Host dependencies (Debian)
sudo apt update
sudo apt install -y git curl python3 python3-venv nodejs npm podman uidmap slirp4netnsuv
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.local/bin/env
uv --versionRootless Podman check
grep "^$(whoami):" /etc/subuid /etc/subgid || \
sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 "$(whoami)"
podman run --rm docker.io/library/alpine echo ok2. Clone and pre-flight
git clone <repo-url> quest && cd quest
uv sync # backend deps into .venv/
cd frontend && npm ci && cd .. # frontend depsAt this point python3 run.py -- (local mode) should boot a working instance on port 9000 with canned test accounts and no credentials.
3. Google OAuth setup
2.1 Pick the public hostname first
2.2 Create the OAuth client in Google Cloud Console
- Pick (or create) a project en Google Cloud Console
- Configure OAuth consent screen (APIs & Services > OAuth consent screen). Elige Internal para Workspace.
- Enable APIs: Gmail API, Calendar API, Drive API, Docs API, Sheets API, Slides API, Tasks API
- Create OAuth client (Web application)
- Register both redirect URIs:
https://quest.yourdomain.com/auth/callbackhttps://quest.yourdomain.com/auth/google-services/callback- Note the client ID and secret
4. Vertex AI setup
4.1 In Google Cloud Console
- Pick a GCP project con billing enabled
- Enable Vertex AI API (aiplatform.googleapis.com)
- For Claude models: enable each model in Vertex AI Model Garden
- Create service account con role Vertex AI User (roles/aiplatform.user)
- Create JSON key y copia al servidor
5. Run it
python3 run.py --prodFirst run walks through bootstrap wizard, builds frontend, installs deps, runs migrations, builds script-runner image, serves on port 8000. Re-run wizard con python3 run.py --prod --bootstrap.
Producción permanente
- Front el servidor con reverse proxy para HTTPS (WebSocket upgrade headers, ≥5 min read timeout)
- Gestiona proceso con systemd
- Plugins se cargan desde plugins/*/plugin.py o directorios extra en QUEST_PLUGIN_PATH
Backup recomendado
- Base de datos SQLite: copiar data/quest.db
- Credenciales JSON: copiar data/service_credentials/
- Configuración: copiar server_config.json
- Plugins personalizados: copiar plugins/*/
Errores habituales
| Error | Causa | Solución |
|---|---|---|
| OAuth redirect URI mismatch | Google rechaza URIs con IPs raw o sin puerto correcto | Asegurar que redirect URIs en Google Cloud Console coincidan exactamente con configuración del servidor (incluyendo protocolo y puerto) |
| Vertex AI model not enabled | Modelo Claude no habilitado en Vertex AI Model Garden | Ir a Vertex AI > Model Garden y habilitar cada modelo antes de usarlo |
| Rootless Podman networking failed | slirp4netns no instalado o UID/GID ranges incorrectos | Verificar instalación de slirp4netns y configurar subuid/subgid con usermod |
| GOOGLE_APPLICATION_CREDENTIALS not set | Service account key no copiado correctamente o ADC no configurado | Asegurar que wizard copie key a data_dir/vertex-service-account.json y run.py exporte GOOGLE_APPLICATION_CREDENTIALS |
Seguridad
- Diseño seguro por defecto: modo privado no permite acceso al internet ni a datos sensibles
- Gestión segura de credenciales: OAuth o claves API con validación en tiempo de ejecución
- Login domain-restricted: solo cuentas en allowed_login_domain pueden sign-in
FAQ basada en evidencia
¿Qué modelos de LLM soporta Quest?
Quest usa Google Cloud Vertex AI para todo el tráfico de LLM (Claude y Gemini). No hay API key de Anthropic ni Gemini directa. Necesitas un proyecto GCP con Vertex AI enabled y service account key.
¿Requiere Docker/Compose?
No, Quest no incluye Dockerfile oficial ni compose.yml. Usa Podman rootless para script-runner sandbox. Para despliegue permanente, front el servidor con reverse proxy (nginx/caddy) y gestiona con systemd.
¿Cómo configurar OAuth de Google?
En Google Cloud Console: crea OAuth client (Web application), registra redirect URIs (https://quest.yourdomain.com/auth/callback y https://quest.yourdomain.com/auth/google-services/callback), obtén client ID/secret, y usa wizard de bootstrap para escribir en server_config.json.
¿Qué es el script runner?
Los scripts escritos por LLMs ejecutan en contenedores Podman efímeros rootless con networking vía slirp4netns (10.0.2.2 con socat forwarding). El image se construye desde Dockerfile.script-runner y se reconstruye automáticamente cuando cambia el Dockerfile.
¿Cómo actualizar Quest?
Clona nuevo repositorio, ejecuta uv sync para backend deps, cd frontend && npm ci para frontend deps, luego python3 run.py --prod --bootstrap para reiniciar con wizard. Para despliegue permanente, actualiza systemd service y reverse proxy config.