# Reference Source: https://docs.oneglanse.com/api-reference Commands, routes, and runtime behavior reference for OneGlanse. ## Useful Commands ```bash theme={null} pnpm local # Start full local stack from local source and refresh Docker service/base images when available pnpm auth # Capture provider sessions locally; prompts to upload to VPS at the end pnpm upload:vps # Re-upload existing local sessions to VPS without re-running the auth flow pnpm self-host # Pull latest published images and start the self-hosted stack; auto-builds locally if your architecture is not published yet pnpm self-host:build # Build from source and start the self-hosted stack pnpm typecheck # Typecheck the monorepo pnpm build # Build all packages ``` ## Key Routes | Route | Description | | ------------ | ------------------------------------------------------------------- | | `/dashboard` | Visibility metrics and GEO scores | | `/prompts` | Manage and run prompts | | `/sources` | Source and citation attribution | | `/providers` | Connect and manage provider auth sessions | | `/schedule` | Manual run trigger (local) or recurring schedule editor (self-host) | | `/people` | Team members | ## App Modes | Capability | Local | Self-Host | | ------------------------- | ----- | --------- | | Interactive provider auth | Yes | — | | Manual prompt runs | Yes | Yes | | Recurring scheduling | — | Yes | | Full data ownership | Yes | Yes | ## Auth Groups Each auth group covers one or more runtime providers: | Auth Group | Covers | | ---------- | ------------------- | | Google | Gemini, AI Overview | | ChatGPT | ChatGPT | | Perplexity | Perplexity | | Claude | Claude | ## Storage Model * **Portable auth bundles** — one per auth group, transferable to VPS, source of truth * **Persistent runtime profiles** — one per provider, machine-local, seeded from the auth bundle If a runtime profile is missing or the auth bundle has changed, the profile is reseeded automatically. Otherwise the existing profile is reused. # Environment Variables Source: https://docs.oneglanse.com/environment-variables Complete reference for all OneGlanse environment variables — required, optional, and their defaults. All variables are read from `.env` in the repo root. If `.env` does not exist, `pnpm local` and `node scripts/run-compose.mjs bootstrap` create it from `.env.example`. If `BETTER_AUTH_SECRET` or `INTERNAL_CRON_SECRET` are blank or still set to `replace-me`, those startup paths generate secure values automatically before launch. *** ## Core Required for any setup path. | Variable | Required | Default | Description | | ---------------------- | -------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------- | | `DATABASE_URL` | Yes | `postgresql://postgres:postgres@localhost:5432/oneglanse` | Postgres connection string | | `CLICKHOUSE_URL` | Yes | `http://localhost:8123` | ClickHouse HTTP endpoint | | `REDIS_HOST` | Yes | `localhost` | Redis hostname in `.env`; Docker self-hosting overrides this internally to `redis` | | `REDIS_PORT` | Yes | `6379` | Redis port | | `REDIS_PASSWORD` | No | `redis` | Redis auth password (set to `redis` in the local Docker setup) | | `BETTER_AUTH_SECRET` | Yes | auto-generated | Session signing secret — auto-generated by setup scripts | | `INTERNAL_CRON_SECRET` | Yes | auto-generated | Internal cron auth token — auto-generated by setup scripts | | `ONEGLANSE_APP_MODE` | No | `local` | `local` or `self-host` — overridden automatically by scripts | | `APP_URL` | No | `http://localhost:3000` | Public-facing URL of the web app | | `API_BASE_URL` | No | `http://localhost:3000` | API base URL (used by tRPC client) | *** ## LLM / Response Analysis At least one LLM key is required to run response analysis after prompt collection. | Variable | Required | Default | Description | | ----------------------- | --------------------- | -------- | --------------------------------------- | | `OPENAI_API_KEY` | Yes (if using OpenAI) | — | OpenAI API key for response analysis | | `ANTHROPIC_API_KEY` | Yes (if using Claude) | — | Anthropic API key for response analysis | | `ANALYSIS_LLM_PROVIDER` | No | `openai` | Which LLM to use: `openai` or `claude` | *** ## Google OAuth Required if you want users to sign in to the OneGlanse web app with Google. | Variable | Required | Default | Description | | ---------------------- | -------- | ------- | -------------------------- | | `GOOGLE_CLIENT_ID` | No | — | Google OAuth client ID | | `GOOGLE_CLIENT_SECRET` | No | — | Google OAuth client secret | Note: these are for web app authentication only. Monitoring Google AI Overview uses a separate browser session captured via `pnpm auth`. *** ## VPS Auth Upload Used when transferring local provider sessions to a self-hosted VPS. | Variable | Required | Default | Description | | ------------------------- | -------- | ------- | ------------------------------------------------ | | `ONEGLANSE_VPS_IP` | No | — | VPS IP — enables `pnpm upload:vps` shorthand | | `AGENT_AUTH_UPLOAD_TOKEN` | No | — | Bearer token to authenticate the auth upload API | *** ## Proxy Required on VPS deployments where direct connections to AI providers are blocked. This is needed because most VPS providers use datacenter IP ranges, and those IPs are commonly blocked or challenged by AI chat products. OneGlanse uses the proxy only for provider website traffic from the VPS browser runtime. For ThorData on VPS, the recommended setup is to whitelist your VPS IP first, generate the endpoint with `Whitelisted IPs` + `API Link`, keep `Sticky session` enabled for prompt runs, and pick a valid country where the providers are supported and your audience is located. | Variable | Required | Default | Description | | ------------------------ | -------- | ------- | ------------------------------------------- | | `THORDATA_PROXY_API_URL` | No | — | ThorData rotating proxy API endpoint | | `PROXY_SCHEME` | No | `http` | Proxy protocol used for ThorData proxy URLs | ### Recommended ThorData setup If you are using ThorData, whitelist your VPS public IP in the ThorData dashboard before generating the proxy endpoint. That keeps authentication simpler and is the recommended setup for OneGlanse on VPS deployments. Use these ThorData endpoint generator settings: * Authentication method: `Whitelisted IPs` * Endpoint type: `API Link` * Session setting: `Sticky session` * Country: choose a valid country where the providers are available and where your target audience is located Use the generated API link as `THORDATA_PROXY_API_URL`. Keep sticky sessions enabled for prompt runs so the provider flow stays on a stable residential IP long enough for sign-in and response collection to complete reliably. Recommended ThorData endpoint generator settings: Whitelisted IPs, API Link, Sticky session, and a valid supported country If you still run into proxy issues after using this setup, email [aryamant20@gmail.com](mailto:aryamant20@gmail.com) or open a pull request if you want support for additional proxy providers or authentication methods. *** ## Agent / Runtime Overrides Override the browser runtime defaults. Only needed if the pinned defaults aren't working for your environment. OneGlanse uses [Camoufox](https://github.com/daijro/camoufox) as its provider browser runtime. This is an anti-fingerprint Firefox-based browser chosen because standard Chrome / Chromium automation is less reliable for authenticated scraping against provider chat UIs. | Variable | Required | Default | Description | | -------------------------- | -------- | --------------------------------- | --------------------------------------------------------- | | `DEBUG_ENABLED` | No | — | Set to `true` to enable verbose agent logging | | `CAMOUFOX_HEADLESS_MODE` | No | `virtual` | Browser display mode: `virtual`, `headful`, or `headless` | | `CAMOUFOX_PYTHON_BIN` | No | — | Path to the Python 3 binary (e.g. `/usr/bin/python3`) | | `CAMOUFOX_PIP_SPEC` | No | `cloverlabs-camoufox==0.5.5` | Camoufox pip package to install | | `CAMOUFOX_BROWSER_CHANNEL` | No | `official/stable/135.0.1-beta.24` | Browser channel to use | *** ## Self-Host Storage & Docker Images | Variable | Required | Default | Description | | -------------------------- | -------- | ------------------------ | ----------------------------------------------------------- | | `ONEGLANSE_STORAGE_ROOT` | No | `/opt/oneglanse/storage` | Host path for persistent auth sessions and browser profiles | | `ONEGLANSE_WEB_IMAGE` | No | GHCR published image | Override the web app Docker image | | `ONEGLANSE_AGENT_IMAGE` | No | GHCR published image | Override the agent Docker image | | `ONEGLANSE_POSTGRES_IMAGE` | No | GHCR published image | Override the Postgres Docker image | *** ## Database Services (Self-Host / Docker Compose) These configure the Postgres and ClickHouse containers. Used by `docker-compose.yml`. | Variable | Required | Default | Description | | --------------------- | --------------- | ------------ | ------------------------ | | `POSTGRES_USER` | Yes (self-host) | `postgres` | Postgres user | | `POSTGRES_PASSWORD` | Yes (self-host) | `postgres` | Postgres password | | `POSTGRES_DB` | Yes (self-host) | `oneglanse` | Postgres database name | | `CLICKHOUSE_DB` | Yes (self-host) | `oneglanse` | ClickHouse database name | | `CLICKHOUSE_USER` | Yes (self-host) | `default` | ClickHouse user | | `CLICKHOUSE_PASSWORD` | Yes (self-host) | `clickhouse` | ClickHouse password | # Getting Started Source: https://docs.oneglanse.com/getting-started Choose the right OneGlanse setup path, then follow a dedicated guide for local or self-hosted deployment. | | Local | Self-Host | | ------------------------- | ----- | --------- | | Fast setup | ✓ | | | Interactive provider auth | ✓ | | | Manual prompt runs | ✓ | ✓ | | Recurring scheduling | | ✓ | | Full data ownership | ✓ | ✓ | *** ## Choose your setup * [Local Setup](/local-setup) Run the full stack on your machine with interactive provider auth and on-demand runs. * [Self-Hosted Setup](/self-hosted-setup) Deploy OneGlanse on your own VPS for recurring schedules and always-on tracking. ## Which path should you pick? * Choose Local if you want the fastest first run, interactive provider auth on your own machine, and manual prompt runs. * Choose Self-Hosted if you want recurring schedules, always-on tracking, and infrastructure you manage yourself. ## Shared requirements Every setup path needs: * An analysis LLM key * Provider sessions captured through the real provider UI * Docker for the database/runtime services used by the app For environment variable details, see [Environment Variables](/environment-variables). For command behavior, see [Reference](/api-reference). # Introduction Source: https://docs.oneglanse.com/introduction OneGlanse is the open-source GEO tracker that shows how your brand appears inside real AI products — ChatGPT, Gemini, Perplexity, Claude, and Google AI Overview. ## Built on real AI outputs OneGlanse captures responses directly from product interfaces, not raw model APIs. That distinction matters. UI responses include: * Citations and sources users actually see * Ranked recommendations and comparisons * Framing, tone, and positioning These layers are stripped out in API responses — but they define real-world visibility. OneGlanse is intentionally **UI-first**: * It opens the real ChatGPT, Gemini, Perplexity, Claude, and Google AI Overview interfaces * It captures the rendered answer that a user actually sees * It analyzes that captured UI response afterward This is the main differentiator in the product. We are not trying to approximate AI visibility by querying official APIs. We measure the live consumer surfaces where recommendation order, citations, source cards, and framing actually appear. If you want the underlying model completion, APIs are useful. If you want GEO truth, the UI matters more. You can read more about the API-vs-UI gap here: [LLM scraped AI answers vs API results](https://surferseo.com/blog/llm-scraped-ai-answers-vs-api-results/). ## Why OneGlanse uses Camoufox OneGlanse uses [Camoufox](https://github.com/daijro/camoufox), an anti-fingerprint Firefox-based browser, for provider sessions. We do not use standard Chrome / Chromium automation as the primary runtime because provider web apps are heavily protected against scripted access. In practice, plain Chrome-style automation is much more likely to trigger sign-in loops, verification challenges, unstable sessions, or failed UI rendering. The issue is not only "headless vs headful". Provider detection systems also look at browser fingerprint consistency and automation signals. Camoufox is materially better suited for this workflow, which is why OneGlanse depends on it for stable authenticated scraping of real chat interfaces. ## Your data stays yours OneGlanse is fully open source and self-hostable. All data — responses, analytics, and auth sessions — lives in infrastructure you control: * Local machine or private VPS * Your own database * Your own provider accounts Analysis requests go directly from your environment to model providers like OpenAI or Anthropic. No proxy servers. No third-party data pipelines. Credentials are never stored externally. ## Why VPS runs need a proxy Self-hosted VPS runs usually come from datacenter IP ranges. Those IPs are routinely blocked, challenged, or rate-limited by AI provider websites. That means a VPS can be perfect for scheduling and persistence, but a poor direct network origin for browser traffic. OneGlanse solves that by routing provider traffic through a residential proxy on VPS deployments. The proxy is not for analytics or API calls. It is specifically for browser access to provider websites from a server environment where datacenter IP reputation would otherwise break collection. ## Deployment options Choose the setup that fits your workflow: * **Local** — run the full stack locally with interactive provider auth * **Self-hosted** — deploy on your own VPS for scheduled tracking and full control → Start with [Getting Started](/getting-started), then follow either [Local Setup](/local-setup) or [Self-Hosted Setup](/self-hosted-setup). # Local Setup Source: https://docs.oneglanse.com/local-setup Run the full OneGlanse stack on your own machine for the fastest setup, interactive provider auth, and manual prompt runs. ## When to choose local Local mode is the fastest way to get started. It is also the most reliable place to capture provider auth because it uses your real machine, your real browser environment, and your normal IP reputation. ## Requirements * Node.js 20+ * pnpm 10+ * Docker If you do not have pnpm: ```bash theme={null} npm install -g pnpm@latest ``` ## 1. Clone and configure ```bash theme={null} git clone https://github.com/aryamantodkar/oneglanse cd oneglanse cp .env.example .env ``` Set your analysis LLM key in `.env`: ```bash theme={null} # Pick one: OPENAI_API_KEY=sk-... # or: ANTHROPIC_API_KEY=sk-ant-... ANALYSIS_LLM_PROVIDER=claude ``` ## 2. Start the local stack ```bash theme={null} pnpm local ``` The app runs at [http://localhost:3000](http://localhost:3000). On first run, OneGlanse: * Starts Postgres, ClickHouse, and Redis * Runs migrations * Bootstraps the browser runtime `pnpm local` uses your latest local source code for the web app and agent. It does not depend on pulling published web or agent images, and it now asks Docker for fresher local service and base images before starting the local infra stack. ## 3. Connect providers Then: 1. Sign up with email 2. Connect your AI provider accounts 3. Add prompts and run If Google OAuth is configured for the web app, users can also sign in with Google. That is separate from monitoring Google AI Overview, which still uses provider sessions captured through the browser auth flow. ## Why OneGlanse uses UI collection OneGlanse does not rely on official model APIs for provider collection. Instead, it opens the real chat interfaces and captures what the provider UI actually renders. That matters because the UI can include: * Citations and source cards * Recommendation ordering * Brand framing and comparisons * Provider-specific formatting that never appears in raw API output This is the core product differentiator. GEO is about what users actually see inside the product surface, not just what a developer API returns. For more context on why UI answers and API answers differ, see [LLM scraped AI answers vs API results](https://surferseo.com/blog/llm-scraped-ai-answers-vs-api-results/). ## Why OneGlanse uses Camoufox Provider websites are authenticated consumer apps with anti-bot protections. OneGlanse uses [Camoufox](https://github.com/daijro/camoufox), an anti-fingerprint Firefox-based browser, because plain Chrome or Chromium automation is much more likely to run into: * Login loops * Forced verification challenges * Unstable sessions * Blocked or degraded collection flows Camoufox gives the runtime a more suitable browser fingerprint profile for authenticated UI collection, which makes provider sessions materially more reliable in practice. ## Related pages * [Getting Started](/getting-started) * [Self-Hosted Setup](/self-hosted-setup) * [Environment Variables](/environment-variables) # Self-Hosted Setup Source: https://docs.oneglanse.com/self-hosted-setup Deploy the OneGlanse app on your own VPS with nginx, SSL, and provider auth upload — step by step with copy-paste commands. ## Interactive setup (recommended) Before you run the setup script, make sure you are logged in as a non-root user with `sudo` access. The script is designed for that flow and will stop if you run it as `root`. If you're on Ubuntu 22.04 / 24.04, the setup script handles everything for the app deployment path — dependencies, repo clone, `.env` config, Docker image pull, nginx, SSL, and firewall — in one session: ```bash theme={null} # On your VPS (as a non-root user with sudo privileges): bash <(curl -fsSL https://raw.githubusercontent.com/aryamantodkar/oneglanse/main/scripts/setup-vps.sh) ``` If your VPS is freshly reinstalled and only has `root`, create a non-root sudo user first, then reconnect as that user before running the setup script: ```bash theme={null} # On the VPS as root, once: adduser deploy usermod -aG sudo deploy # Optional: copy your existing root SSH key access to the new user install -d -m 700 -o deploy -g deploy /home/deploy/.ssh cp -a /root/.ssh/authorized_keys /home/deploy/.ssh/authorized_keys chown deploy:deploy /home/deploy/.ssh/authorized_keys chmod 600 /home/deploy/.ssh/authorized_keys # Then reconnect as the new user: ssh deploy@YOUR_VPS_IP ``` When the script prompts for `Your domain for the app`, enter the hostname you want to serve OneGlanse on, such as `app.yourdomain.com`. The script configures nginx and requests the TLS certificate for that exact domain. Or clone first and run locally: ```bash theme={null} git clone https://github.com/aryamantodkar/oneglanse /tmp/oneglanse bash /tmp/oneglanse/scripts/setup-vps.sh ``` The script is interactive — it asks for your domain, LLM key, and proxy URL, then does the rest. If you leave the auth upload token blank, it generates one automatically, and it handles first-run Docker group access for the setup user in the same session. Do not use `curl ... | bash` here. Because the setup flow is interactive, piping the script body into `bash` steals stdin from the prompts. `bash <(...)` keeps stdin attached to your terminal, so the prompts work correctly. The VPS flow is intentionally simple: * it pulls the published Docker images * it does not build the app on your server by default * `git pull` updates the deployment files, and the next bootstrap pulls the latest published app images *** ## Manual setup This guide deploys OneGlanse on a fresh Ubuntu 22.04 / 24.04 VPS. At the end you'll have: * OneGlanse running behind nginx with HTTPS * Postgres, ClickHouse, and Redis running in Docker * Provider sessions uploaded from your local machine This guide intentionally deploys only the app. * The landing site is deployed separately on Vercel * The docs are deployed separately on Mintlify Important context before you start: * OneGlanse collects responses from real provider UIs, not official model APIs * provider auth is captured locally with `pnpm auth` * VPS browser traffic needs a residential proxy because datacenter IPs are often blocked by provider websites *** ## 1. Provision the VPS Any provider works (Hetzner, DigitalOcean, Vultr, etc.). Minimum spec: | | Minimum | Recommended | | ---- | ------------ | ------------ | | CPU | 2 vCPU | 4 vCPU | | RAM | 4 GB | 8 GB | | Disk | 40 GB SSD | 80 GB SSD | | OS | Ubuntu 22.04 | Ubuntu 24.04 | Point a DNS A record at your VPS IP before continuing — nginx and certbot need it: ``` A app.yourdomain.com → YOUR_VPS_IP ``` If you do not have a real domain yet and only need a temporary launch/test hostname, a wildcard DNS helper such as `YOUR_VPS_IP.nip.io` or `YOUR_VPS_IP.sslip.io` also works. *** ## 2. Install dependencies SSH into your VPS as your non-root sudo user and run: ```bash theme={null} sudo apt-get update # Docker curl -fsSL https://get.docker.com | sh sudo usermod -aG docker $USER newgrp docker # Node.js 20 curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs # git sudo apt-get install -y git # nginx + certbot sudo apt install -y nginx certbot python3-certbot-nginx ``` *** ## 3. Clone and configure ```bash theme={null} git clone https://github.com/aryamantodkar/oneglanse /home/$USER/oneglanse cd /home/$USER/oneglanse cp .env.example .env ``` Edit `.env` and fill in the required values: ```bash theme={null} nano .env ``` Minimum required changes: ```bash theme={null} # Your public URL APP_URL=https://app.yourdomain.com API_BASE_URL=https://app.yourdomain.com # LLM key for response analysis — pick one: OPENAI_API_KEY=sk-... # or: # ANTHROPIC_API_KEY=sk-ant-... # ANALYSIS_LLM_PROVIDER=claude # Residential proxy — required on VPS THORDATA_PROXY_API_URL=https://your-thordata-endpoint # Auth upload token — any strong random string AGENT_AUTH_UPLOAD_TOKEN=replace-with-a-strong-secret ``` If `BETTER_AUTH_SECRET` or `INTERNAL_CRON_SECRET` are still unset or left as `replace-me`, `node scripts/run-compose.mjs bootstrap` generates them automatically before Docker starts. Why the proxy is mandatory on VPS: * VPS traffic usually originates from datacenter IP ranges * provider websites frequently challenge or block those IPs * OneGlanse collects from authenticated web UIs, so network reputation matters The proxy is what makes VPS-based scheduling viable. Without it, direct provider access from the VPS is often unreliable. *** ## 4. Start the stack ```bash theme={null} node scripts/run-compose.mjs bootstrap ``` On a fresh server, this can take several minutes because Docker has to pull the published images. This pulls the published Docker images and starts: * Web app on **127.0.0.1:3000** (loopback only, for nginx) * Agent worker (internal) * Postgres on port **5432** (internal) * ClickHouse on port **8123** (internal) * Redis on port **6379** (internal) Verify everything is up: ```bash theme={null} docker ps ``` You should see containers for `web`, `agent-worker`, `postgres`, `clickhouse`, and `redis`. *** ## 5. Configure nginx Create the nginx site config: ```bash theme={null} sudo nano /etc/nginx/sites-available/oneglanse ``` Paste this — replace `app.yourdomain.com` with your domain: ```nginx theme={null} server { listen 80; server_name app.yourdomain.com; location / { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_cache_bypass $http_upgrade; proxy_read_timeout 120s; } } ``` Enable the site and reload: ```bash theme={null} sudo ln -s /etc/nginx/sites-available/oneglanse /etc/nginx/sites-enabled/ sudo rm -f /etc/nginx/sites-enabled/default sudo nginx -t sudo systemctl reload nginx ``` *** ## 6. Enable HTTPS with Let's Encrypt ```bash theme={null} sudo certbot --nginx -d app.yourdomain.com ``` Certbot will: 1. Obtain a certificate 2. Automatically update the nginx config to redirect HTTP → HTTPS 3. Set up auto-renewal via a systemd timer Verify auto-renewal works: ```bash theme={null} sudo certbot renew --dry-run ``` *** ## 7. Upload provider auth sessions Provider auth must be captured on your **local machine** (it needs a real browser). Once captured, upload the sessions to the VPS. OneGlanse uses [Camoufox](https://github.com/daijro/camoufox), an anti-fingerprint Firefox-based browser, for this flow. That is intentional: plain Chrome / Chromium automation is more likely to trigger login loops, verification challenges, or unstable sessions on provider websites. Camoufox is a better fit for authenticated scraping against anti-bot-protected chat interfaces. **On your local machine** — set these in your local `.env`: ```bash theme={null} ONEGLANSE_VPS_IP=YOUR_VPS_IP AGENT_AUTH_UPLOAD_TOKEN=replace-with-a-strong-secret # same as on VPS ``` Then open the provider auth flow and sign in to each provider: ```bash theme={null} pnpm auth ``` At the end of the sign-in flow, `pnpm auth` will ask whether to upload to the VPS — answer `y`. Sessions are transferred and the VPS agent picks them up immediately. When a session expires later and you want to re-upload without going through the sign-in flow again: ```bash theme={null} pnpm upload:vps ``` *** ## 8. Open the app Navigate to `https://app.yourdomain.com`, create your account, and start adding prompts. Before you run prompts from the VPS, make sure `THORDATA_PROXY_API_URL` in `/home/$USER/oneglanse/.env` points to your real residential proxy endpoint. If you deployed with a placeholder or later changed the proxy configuration, update that value and rerun: ```bash theme={null} cd /home/$USER/oneglanse node scripts/run-compose.mjs bootstrap ``` Without the correct proxy endpoint, VPS prompt runs are likely to be blocked, challenged, or less accurate. *** ## Updates Pull and redeploy without downtime: ```bash theme={null} cd /home/$USER/oneglanse git pull node scripts/run-compose.mjs bootstrap ``` *** ## Firewall Allow only the ports nginx needs. For auth uploads, port `3333` is needed only for the agent upload API: ```bash theme={null} sudo ufw allow OpenSSH sudo ufw allow 'Nginx Full' sudo ufw enable ``` If your local machine has a stable public IP, prefer allowing `3333/tcp` only from that source: ```bash theme={null} sudo ufw allow from YOUR_LOCAL_PUBLIC_IP to any port 3333 proto tcp ``` If your local IP changes often, you can allow `3333/tcp` broadly instead and rely on `AGENT_AUTH_UPLOAD_TOKEN` for authentication: ```bash theme={null} sudo ufw allow 3333/tcp ``` The app ports (3000, 5432, 8123, 6379) stay internal. Port `3333` is only for `pnpm upload:vps`, which sends provider sessions to `http://YOUR_VPS_IP:3333/auth/sessions`. On self-hosted deployments, the web app's provider management endpoints stay behind app authentication, while the upload API on `3333` is protected by the bearer token in `AGENT_AUTH_UPLOAD_TOKEN`. *** ## Troubleshooting **502 Bad Gateway** — the web container isn't running yet. Check: ```bash theme={null} docker logs oneglanse-web --tail 50 ``` **SSL certificate failed** — DNS hasn't propagated yet. Wait a few minutes and retry: ```bash theme={null} sudo certbot --nginx -d app.yourdomain.com ``` **Providers disconnected after reboot** — sessions survive restarts (they're in the volume at `/opt/oneglanse/storage`). If they expire, re-run `pnpm upload:vps` from your local machine. **VPS ran out of disk** — ClickHouse data grows over time. Check usage: ```bash theme={null} df -h docker system df ``` # Troubleshooting Source: https://docs.oneglanse.com/troubleshooting Solutions for common issues when setting up and running OneGlanse. *** ## Camoufox fails to start **Symptom:** Agent crashes immediately with a Python or pip error. **Cause:** Python 3 is not on the PATH or the wrong binary is being used. **Fix:** Find your Python 3 binary and set it explicitly: ```bash theme={null} which python3 # e.g. /opt/homebrew/bin/python3 ``` Add to `.env`: ```bash theme={null} CAMOUFOX_PYTHON_BIN=/opt/homebrew/bin/python3 ``` Then restart with `pnpm local`. *** ## Redis connection refused **Symptom:** App or agent logs show `ECONNREFUSED 127.0.0.1:6379`. **Cause:** The Redis Docker container is not running. **Fix:** Check that Docker is running and the containers are up: ```bash theme={null} docker ps ``` If the containers aren't listed, restart with `pnpm local`. If Docker itself isn't running, start it first. *** ## ClickHouse unavailable on first run **Symptom:** Dashboard shows no data, or logs show a ClickHouse connection error shortly after startup. **Cause:** ClickHouse takes 10–20 seconds to fully initialize on first boot. **Fix:** Wait a moment and reload the page. If it persists, check the container: ```bash theme={null} docker logs clickhouse_db ``` *** ## Provider auth not saving **Symptom:** A provider still shows as disconnected after you finish the local auth flow. **Cause:** The Camoufox window was closed before the session was fully written. **Fix:** Open the provider connection again, complete the full sign-in flow (including any 2FA or confirmation steps), and wait for the checkmark to appear in the OneGlanse UI before closing the browser window. *** ## Google sign-in is unavailable **Symptom:** No Google sign-in button appears on the login page. **Cause:** `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` are not set in `.env`. **Fix:** Add them to `.env`: ```bash theme={null} GOOGLE_CLIENT_ID=your-client-id GOOGLE_CLIENT_SECRET=your-client-secret ``` Note: these control sign-in to the OneGlanse web app itself. They are separate from the Google / Gemini / AI Overview provider connections used for monitoring. *** ## Agent not processing prompts **Symptom:** Prompts are queued but no responses appear. **Causes and fixes:** 1. **Worker not started** — `pnpm local` starts both web and agent. If you started the web app separately, also run `pnpm dev:agent`. 2. **Provider auth missing** — run `pnpm auth` locally and confirm at least one provider completes sign-in. If a provider is still disconnected, rerun the auth flow for that provider. 3. **Redis not reachable** — see the Redis section above. *** ## Self-host: image pull fails **Symptom:** `node scripts/run-compose.mjs bootstrap` fails with a Docker pull error, `unauthorized`, or an architecture mismatch such as `no matching manifest`. **Cause:** Either the GHCR images are unavailable, you're not authenticated with GHCR, or the published image has not been published for your current CPU architecture yet. **Fix:** Check outbound access to GHCR and Docker Hub, then retry: ```bash theme={null} node scripts/run-compose.mjs bootstrap ``` If the only problem is an architecture mismatch, bootstrap now automatically falls back to a local Docker build on that machine. If you're maintaining a fork or explicitly want a source build, you can still run `pnpm self-host:build` directly. *** ## Migrations fail on startup **Symptom:** The `migrate` container exits with an error; the web app won't start. **Cause:** Postgres wasn't ready when migrations ran, or there's a schema conflict. **Fix:** ```bash theme={null} # Check migration logs docker logs oneglanse-migrate # Re-run migrations manually pnpm db:migrate ``` If there's a schema conflict from a previous installation, check the Drizzle migration files in `packages/db/drizzle/`. *** ## VPS: sessions not transferring **Symptom:** `pnpm upload:vps` runs but providers still show as disconnected on the VPS. **Fixes:** 1. Confirm the VPS agent is running: `curl http://YOUR_VPS_IP:3333/health` 2. Confirm port `3333/tcp` is allowed by your VPS firewall or cloud security group 3. Check `ONEGLANSE_VPS_IP` and `AGENT_AUTH_UPLOAD_TOKEN` match your VPS `.env` 4. If `pnpm upload:vps` returns `401 Unauthorized`, the upload token on your local machine does not match the VPS `AGENT_AUTH_UPLOAD_TOKEN` 5. Check agent logs on the VPS: `docker logs oneglanse-agent-worker`