Quadrillion Technical Onboarding: Enterprise

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. Each server is unlocked with a BYOK activation key: it puts the server in bring-your-own-keys mode, where model calls use your own provider accounts. You install in two places: the Qualia server on the Linux host, and the desktop app on your laptop.

By default, Quadrillion issues your BYOK activation keys and nothing else is needed. Firms that prefer people to mint their own keys can use any supported sign-in method.

Installation

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.
  • You do not need to expose notebook files directly. Qualia only needs the server’s host and port.

Step 3: Get your BYOK activation key

One key per person. Keys start with qd_live_, are shown once, and should be treated like passwords. A BYOK activation key is what entitles your organization to run Qualia against your own provider accounts.

  • Option A — Quadrillion issues your BYOK keys (default). Tell us how many people will run Qualia. We hand the keys to your admin over a secure channel, never by email. No Quadrillion accounts, organization, or identity-provider setup needed. To revoke or replace a key, ask us.
  • Option B — people mint their own keys. Each person signs in at quadrillion.ai/login with any supported method, opens API Keys, clicks Create new key, and copies the key from the API key created dialog. You can revoke your own keys there at any time.

Step 4: 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.
  • On the sign-in screen, click enter your activation key, paste the key, and click Activate. Do not use Sign in with SSO or Continue with: those sign in as a standard account and route model calls through Quadrillion.

Step 5: 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.
  • When the banner says the server’s keys differ from this computer, click Review, then Import. This copies your activation key onto the server without displaying it.
  • Choose your workspace with Open remote folder… in the same picker, and switch it anytime from there without restarting the server.

Alternative to Steps 4–5: 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. On the first-run sign-in screen, click enter your activation key, paste the key, and click Activate. The key is stored on the server. You pick a workspace folder afterward, as in Step 5.
  • 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.

Unattended servers

  • Start the binary with the key in its environment: QUADRILLION_ACTIVATION_KEY=qd_live_... ./qualia --serve-frontend. The environment key wins over a stored one and skips the sign-in step.
  • The key then sits in plaintext in your process manager’s environment, so prefer activating once interactively where you can.
  • Keys entered interactively live in an encrypted vault under ~/.config/io.quadrillion.qualia. Without an OS keychain (typical over SSH), Qualia uses a 0600 file instead. Force that with QUALIA_CREDENTIAL_STORE=file.

Bring your own keys

  • After activation, onboarding asks for your OpenAI, Anthropic, or Google keys or custom endpoints. Skip and add them later under Settings > Models > Provider access.
  • Each provider is routed independently. Choose Quadrillion proxy for a provider to send its requests through Quadrillion, authenticated by the activation key.
  • Azure OpenAI and Azure Foundry endpoints are supported with Entra ID or key authentication. Details in API Keys.

Network requirements

Qualia needs outbound HTTPS access to:

  • quadrillion.ai and quadrillion.io, and their subdomains - licensing, activation, updates, and proxied LLM calls when a provider is set to the Quadrillion proxy. 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.
  • Your model providers’ endpoints (api.openai.com, api.anthropic.com, Google, or your Azure endpoints) from the Linux server.
  • 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.

With Option A, laptops need no access to quadrillion.ai. With Option B, laptops need browser access to quadrillion.ai and to whichever sign-in provider they use.

No inbound ports are required - Qualia listens on localhost only - and standard HTTPS proxies are supported via the usual HTTPS_PROXY environment variable. For reaching the server from your laptop, 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. Apple Silicon or Intel.
  • 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, activation key, and history live outside the install directory and are preserved.

Multi-user

Single-user per instance: each person activates their own server with their own key. Several people can share one Linux host, each running their own server under their own Unix account on its own BACKEND_PORT. Access to a server is controlled by SSH, as in Step 2. Shared, multi-member workspaces are a Qualia Cloud feature.

Offboarding and rotation

  • Option A keys: ask us to revoke or replace a key, then stop that person’s server and reclaim the host.
  • Option B keys: revoke them yourself under API Keys at quadrillion.ai.
  • Replacing a key on a server: choose Use a different account on the sign-in screen to clear the stored key, then activate with the new one.
  • Provider keys on the server are yours and are unaffected by Quadrillion-side revocation.

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.

Sign-in methods

Sign-in to quadrillion.ai is only needed for Option B, to mint keys. Any of these work:

  • Your company identity provider (SSO): type your work email and click Continue with SSO. Ask us to connect your identity provider if it is not already.
  • Microsoft: work, school, or personal accounts, with no setup on your side.
  • Google: Google Workspace or personal accounts.
  • GitHub.

Whichever method you use, the Linux server never sees it; it only holds the activation key.

Questions, support, bugs

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

Enterprise Setup — Quadrillion