Quadrillion Technical Onboarding

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 install in two places: the Qualia server on the Linux host, and the desktop app on your laptop.

Step 1: Install the Qualia server on the Linux host

  • SSH into the Linux host — the machine that already has the notebooks, files, data mounts, and compute you want agents to use — and run the Linux install command from quadrillion.ai/download.
  • Start the server with ./qualia. It starts without a workspace folder; you choose one from the desktop app after connecting.
  • The server listens on port 5001 by default; set the BACKEND_PORT environment variable to change it.
  • Keep the server and the desktop app on matching versions.

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), 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.
  • Do not bind with --host 0.0.0.0. It drops the cross-site session cookie the desktop app authenticates with, so the app cannot stay signed in.
  • Do not add --serve-frontend for the desktop app. That flag is only for the browser option below, and a server started with it does not accept the desktop app.
  • You do not need to expose notebook files directly. Qualia only needs the server's host and port.

Step 3: Install the Qualia desktop app on your laptop

  • Open quadrillion.ai/download, download the installer for your laptop's operating system (macOS, Windows, or Linux), and run it.
  • Sign in with your work email. Qualia stores the credential for you — there is no key to create or paste. (BYOK deployments use an activation key instead.)

Step 4: Connect the desktop app to the Linux server

  • Open the workspace picker in the center of the titlebar, 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 Qualia server's port from Step 1. For a direct connection, enter the server's https:// URL.
  • Choose your workspace with Open remote folder... in the same picker, and switch it anytime from there without restarting the server.

Alternative to Steps 3–4: 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. Nothing is installed on the laptop.
  • On the Linux host, start the self-host binary with ./qualia --serve-frontend. It serves both the headless backend and the browser frontend on one HTTP port, defaulting to 127.0.0.1:5001, and allows the matching browser origin automatically.
  • On the laptop, forward that port and open it in a browser: ssh -N -L 5001:127.0.0.1:5001 user@linux-host, then http://localhost:5001. The frontend, API, and live socket all use that one forwarded origin, so nothing else needs forwarding. First-run setup asks you to sign in; you pick a workspace folder afterward, the same way as in Step 4.
  • To use different ports, change them in the forward itself: ssh -N -L <local-port>:127.0.0.1:<server-port>. Set BACKEND_PORT to the server port, and if the local port differs from it, set FRONTEND_PORT to the local port so the server allows that browser origin. For example BACKEND_PORT=5010 FRONTEND_PORT=9000 ./qualia --serve-frontend, then ssh -N -L 9000:127.0.0.1:5010 user@linux-host and open http://localhost:9000.

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

  • Open quadrillion.ai/download and download the installer for your operating system: macOS, Windows, or Linux (.deb or .AppImage, x64).
  • Run the installer on the machine where you want to use Qualia, then open the app.
  • Sign in with your work email. Qualia stores the credential for you — there is no key to create or paste. (BYOK deployments use an activation key instead.)
  • Choose the local folder that contains your notebooks, code, and project files. That folder becomes your workspace.

Bring your own keys

In BYOK deployments, click For enterprise deployments, enter your activation key on the sign-in screen. Create your own key at quadrillion.ai under Dashboard > API Keys (shown once, one per person) and paste it here. Qualia then asks for your OpenAI, Anthropic, and Google keys and calls those providers directly.

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.
  • quadrillion-backend-prod-releases.s3.amazonaws.com - downloads from /download/* redirect here with a presigned URL. Allowlisting only quadrillion.ai will make installs and updates fail.
  • 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. For a remote Linux setup, see Step 2 above.

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.

System requirements

  • macOS: 12 (Monterey) or later on Apple Silicon (M1 or newer).
  • Windows: Windows 10 or later (64-bit).
  • Linux: x86_64, glibc 2.31+ - Ubuntu 20.04, Debian 11, RHEL 9, or newer equivalents. Applies to both the server binary and the desktop packages. ARM64 is not available yet.
  • 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.

The Linux server binary does not self-update. Stop it, extract the new tarball over the old binary, and restart. Settings, workspace, and history live outside the install directory and are preserved.

Multi-user

Both setups in this guide are single-user per instance: each person signs in with their own account, and there is no shared workspace or team-level state between installs. Several people can share one Linux host, each running their own server on its own BACKEND_PORT against their own workspace folder. Shared, multi-member workspaces are a Qualia Cloud feature.

Customization

  • Rules. Persistent instructions the agent reads on every prompt - a common first rule is telling Qualia where your codebase lives, since it is often not next to your notebooks. Add one from the gear menu in the titlebar, under Customize agent > Rules.
  • 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. Connect it under Settings > Integrations > Slack, then 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