Quadrillion Technical Onboarding

This guide walks your tech team through everything needed to get Qualia running, including installation, networking, and day-to-day customization.

Installation

Use this setup when your notebooks, data, or compute live on a Linux server, cluster login node, VM, or cloud machine, while you use the Qualia desktop app from your laptop.

You will install Qualia in two places:

  • On the Linux host: install the Qualia server. This is where notebooks and data live.
  • On your laptop: install the Qualia desktop app. This is the frontend you use day to day.

Step 1: Install the Qualia server on the Linux host

  • SSH into the Linux host.
  • Run the Linux install command from quadrillion.ai/download.
  • Start the server with --base_path none — you choose the workspace folder from the desktop app after connecting, and can switch it anytime without restarting.
  • For example: ./qualia --base_path none
  • Optionally, pass a directory to open it by default: ./qualia --base_path /home/you/research. You can still change folders from the app afterward.
  • The server accepts connections from the Qualia desktop app automatically (over the SSH option in Step 2). Keep the server and the desktop app on matching versions.
  • The server listens on port 5001 by default; set the BACKEND_PORT environment variable to change it.
  • The Qualia server should run on the same Linux machine that has access to the notebooks, files, data mounts, and compute environment you want agents to use.

Step 2: Make the server reachable from your laptop

  • SSH (recommended): nothing extra to set up. The Qualia desktop app tunnels to the server over the same SSH access you used in Step 1, so no ports need to be exposed. The connection uses SSH port 22 by default (configurable in the connection dialog) and requires TCP forwarding (AllowTcpForwarding yes in sshd_config, the OpenSSH default).
  • Direct connection (advanced): only if you cannot use SSH. Bind the server to its LAN address with --host <server-ip> (for example --host 192.168.1.50, not --host 0.0.0.0), put an HTTPS reverse proxy (nginx or caddy, with a certificate your laptop trusts) in front of it, and point the app at the https:// URL. Plain http:// to a remote host is not supported, so without TLS, use SSH.
  • You do not need to expose notebook files directly. Qualia only needs access to the server host and port.

Alternative: open Qualia in a browser through a port forward

  • Use this option when your organization cannot run the desktop app's built-in remote connection flow. Install the self-host Linux artifact, which is a single qualia binary that serves both the headless backend and the browser frontend on one HTTP port.
  • On the Linux host, start the binary: ./qualia --serve-frontend. This starts without a workspace folder; the browser opens the first-run setup and then lets you choose a workspace. The server defaults to 127.0.0.1:5001 in this mode and automatically allows the matching browser origin.
  • On the laptop, forward that port over SSH: ssh -N -L 5001:127.0.0.1:5001 user@linux-host.
  • Open http://localhost:5001 in a browser on the laptop. The frontend, API, and live socket connection all use the same forwarded origin.
  • If port 5001 is already in use on the Linux host, set BACKEND_PORT when starting the server and forward to that port. For example: BACKEND_PORT=5010 ./qualia --serve-frontend, then ssh -N -L 5010:127.0.0.1:5010 user@linux-host and open http://localhost:5010.
  • If the Linux host still uses 5001 but you forward a different local browser port, set FRONTEND_PORT to that local port when starting the server. For example: FRONTEND_PORT=9000 ./qualia --serve-frontend, then ssh -N -L 9000:127.0.0.1:5001 user@linux-host and open http://localhost:9000.

Step 3: Install the Qualia desktop app on your laptop (desktop-app setup)

  • On your laptop, open quadrillion.ai/download.
  • Download the macOS or Windows installer.
  • Install Qualia on your laptop.
  • Click For enterprise deployments, enter your activation key.
  • Paste in the activation key we have given you.
  • This will lead you to directly paste in BYOK API keys for OpenAI, Anthropic, and Google model providers.

Step 4: Connect the desktop app to the Linux server (desktop-app setup)

  • Open Qualia on your laptop.
  • Click the connection indicator in the bottom-left corner, then choose Connect to remote....
  • For SSH, enter the Linux host, SSH port (22 unless your host uses a custom one), your SSH username and key, and the remote backend port (the Qualia server's port from Step 1). For a direct connection, enter the server's https:// URL (a TLS endpoint in front of a server started with --host <server-ip>) — the app rejects plain http:// URLs to remote hosts because they cannot keep you signed in.
  • Qualia connects to the server. If you started it with --base_path none, pick your workspace folder from the bottom-left switcher; otherwise it opens the directory you passed. You can switch the remote folder anytime from the bottom-left without restarting the server.

Use this setup when your notebooks, data, and day-to-day work all live on your Mac or Windows machine.

Step 1: Download Qualia

Step 2: Install the app locally

  • Run the installer on the same machine where you want to use Qualia.
  • Open Qualia after installation finishes.

Step 3: Enter your activation key

  • Click For enterprise deployments, enter your activation key.
  • Paste in the activation key we have given you.
  • This will lead you to directly paste in BYOK API keys for OpenAI, Anthropic, and Google model providers.

Step 4: Open your local workspace

  • Choose the local folder that contains your notebooks, code, and project files.
  • Qualia will use that folder as your workspace.

Network requirements

Qualia needs outbound HTTPS access to:

  • quadrillion.ai and quadrillion.io, and their subdomains - licensing, auth, updates, and standard-account LLM proxying. Both are required: the service is moving to quadrillion.ai, and released clients continue to reach quadrillion.io for updates and downloads.
  • sentry.io - crash and error reporting.
  • otlp-gateway-prod-us-east-3.grafana.net - performance metrics and traces.

If your network blocks the sentry.io or Grafana endpoints, Qualia keeps working - only crash reporting and performance telemetry are affected. Let us know if you need telemetry turned off for your deployment.

No inbound ports are required for local desktop usage - Qualia listens on localhost only - and standard HTTPS proxies are supported via the usual HTTPS_PROXY environment variable.

Networks that intercept TLS with a corporate root CA are supported: the server trusts the operating system’s certificate store, so a corporate CA installed there works automatically. A custom CA bundle can also be supplied explicitly via the standard SSL_CERT_FILE or REQUESTS_CA_BUNDLE environment variables when starting the server.

For a remote Linux setup, the desktop app reaches the Qualia server either over an SSH tunnel (recommended; no exposed ports needed; SSH port configurable, default 22) or, for advanced setups, directly over HTTPS — a TLS endpoint in front of a server bound with --host <server-ip>. Do not bind with --host 0.0.0.0 for desktop-app access; that mode is intended for non-browser API clients and cannot keep the desktop app signed in.

System requirements

  • macOS: 11 (Big Sur) or later. Apple Silicon or Intel.
  • Windows: Windows 10 or later (64-bit).
  • Linux (for the server binary): glibc 2.31+ - Ubuntu 20.04, Debian 11, RHEL 9, or newer equivalents.
  • RAM: 8 GB minimum, 16 GB recommended for larger notebooks.
  • Disk: 2 GB free for the application plus room for your notebooks, local DB, and logs.

Updates

Qualia checks for updates on launch and offers to download them in the background. Auto-update can be turned off in settings for managed fleets, in which case installers can be distributed manually from quadrillion.ai/download.

Multi-user

Qualia is currently single-user per machine: each user installs Qualia on their own workstation and signs in with their own account, and there is no shared workspace or team-level state between installs.

Customization

  • Rules. Persistent instructions the agent reads on every prompt. Many firms keep their codebase in a different location from their notebooks, so a common first rule is telling Qualia where the codebase lives and how to reference it. Open the Rules pane in the bottom-left sidebar to add one.
  • Skills. Reusable workflows the agent can invoke automatically or on demand (e.g., a standard research playbook, a recurring analysis workflow).
  • MCP integrations. Connect external tools (internal databases, APIs, ticketing systems) to Qualia using the Model Context Protocol.
  • Autonomous mode. Let Qualia run independently for hours on a task, with progress updates sent to Slack.
  • Slack integration. Once connected in settings, DM @Qualia or @-mention it in a channel to start a new session; replies in the thread continue the conversation.

Questions, support, bugs

If you run into issues, please book a meeting and we’ll debug as soon as we can.

Technical Setup — Quadrillion