Appliance export

Requires the Pro plan or above.

Some projects can’t run on a shared cloud at all. A hospital system whose data isn’t allowed to leave its own network. A government contract that requires on-prem delivery. A reseller shipping the same product into a dozen customer environments that must never depend on each other. For those, “run it in our cloud, just with extra isolation” isn’t good enough — the whole system has to run somewhere the customer controls.

Appliance export is how you deliver that: a single sealed, signed archive that carries the application, its agents, the governed data model and the policies that enforce it, plus a runtime to run all of it. You install it with Docker Compose on infrastructure you or your customer owns. Once it’s up, it never calls qRaptor again to serve traffic — qRaptor is only contacted to pull the images at install or upgrade time.

⚠️

Early access. Appliance export has been installed and served off-platform, but it is not yet generally available. Air-gapped install doesn’t exist yet, and the supported install target is Docker Compose on linux/amd64 only. Read What is not supported yet before you plan a delivery around it.

Is this what you need?

qRaptor gives you three ways to put a project in front of users, and they solve different problems:

	Where it runs	Use it when
Managed cloud	qRaptor’s infrastructure	The default. No constraint on where data or compute lives.
Remote executors	Mostly qRaptor, with specific steps running inside your network	An agent’s reasoning and orchestration can stay on the managed cloud, but one step — a query, a tool call — has to touch a private database or internal API.
Appliance export (this section)	Entirely on infrastructure you control	The whole system — app, agents, data, policies — has to run with no dependency on qRaptor’s cloud at all, including after it’s installed.

If only a piece of an agent’s work needs to stay inside your network, use a remote executor — it’s far less to operate than a whole appliance. Reach for an appliance when nothing can be managed centrally: no shared database, no shared runtime, no ongoing connection.

Prerequisites

Admin role.
A project with at least one agent, app or multi-agent system published to production — an export carries what’s live, not work in progress.
A linux/amd64 host with Docker and Docker Compose v2, for installing it.

What you get

One file — appliance-<project>-<version>.tar.gz — that unpacks to a directory containing:


`compose.yaml`	The full service topology, every image pinned by digest
`bundle/`	The sealed configuration: app definition, roles, permissions, page access, data governance (tables, columns, row filters), pinned agent and multi-agent-system versions, schedules, Keycloak realm, project configs, LLM configuration and runtime config
`manifest.yaml` + `manifest.sig`	A SHA-256 of every sealed file, and a detached Ed25519 signature over it
`install.sh`, `verify.sh`	Verify the archive, then pull by digest and start
`.env.example`	Every value you need to supply, starting with your public URL
`config/api-keys.yaml`	Which agents can be called with an API key, and the keys — all off until you edit it. Not sealed, so editing it never fails verification
`db-init/`, `seed/`, `otel/`	Database schema, Keycloak realm seeding, and an optional telemetry collector
`README.md`	Install instructions generated for this specific export, and the endpoints of every agent it carries

The archive is deterministic: the same project at the same version produces a byte-identical archive, and the download page shows its SHA-256.

Page-level access control, role and permission checks, and data governance (row filters and column masks) are all enforced inside the appliance exactly as they are on the managed cloud — the rules travel in the bundle, and the same services that enforce them in Studio enforce them here.

ℹ️

No secrets travel in the bundle. LLM keys, database passwords and other credentials are referenced by environment-variable name only — you supply the values at install time. Every export runs a secret scan, and a finding fails the export rather than shipping.

How this section is organised

Exporting a project — the wizard, what you can include, and how to prepare a project beforehand.
Installing it — getting it running on your own infrastructure: choosing its address, filling in .env, connecting models, upgrading.
Agent exposure — choosing which agents can be called from your own code, and managing their API keys.
Signing keys — the published public keys and how to verify an archive actually came from qRaptor.

What is not supported yet

Appliance v1 is deliberately narrow. These are not available today:

Air-gapped install. The install pulls from a registry; images are not shipped inside the archive.
Kubernetes. Docker Compose only — no Helm chart or manifests.
arm64 hosts. Images are linux/amd64 only. An arm64 host pulls successfully and then fails to execute.
Document version history. Documents travel when you select Documents and assets, but only each one’s latest version — see Files and documents.
The app’s Users screen. Listing and managing users from the generated app’s Users screen doesn’t work in an appliance yet. Roles and permissions work, and users sign in normally.
Database triggers. A trigger doesn’t travel into an appliance export, and the export doesn’t warn when a project has one.
MCP tool catalogs and marketplace tools. These fail fast with a clear error rather than hanging. Built-in tools work, and MCP credentials from your configurations resolve.
Voice.
Federated / remote executors. The appliance runs work locally.
External identity providers (SSO). Password and email login work out of the box; an exported app starts with phone login, OTP and self-registration off regardless of how your organization configured them.
Studio. Nothing in the appliance authors agents or configurations; agent, system and schedule versions are pinned at export.

ℹ️

An export with no application tier (agents only) starts its runtime services but serves nothing at / — the export warns you when this is the case.

Common issues

The export fails the coherence check. Run a dry run and read the specific error — it names the missing agent, empty table, or credential-less LLM route causing it. Fix the project and re-run the dry run before spending time on a real export.
Sign-in fails right after the password step, or times out. The appliance can’t call its own public address from inside the host. Set QR_GATEWAY_LOOPBACK_HOST.
install.sh or verify.sh refuses to continue. A clean archive exits 0. A refusal names what didn’t match — a tampered file, a key that doesn’t match the signature, or (in a dev export) no signature at all. Don’t override a refusal without knowing which of these it is — see Signing keys.
A knowledge base you expected isn’t there. It has to be selected in the export wizard — nothing is included automatically. Re-export with it checked.
An automation that used to run on a row change stopped working after install. Database triggers don’t travel yet — see What is not supported yet.

Remote executors — keep the platform managed, but run individual steps inside your own network.
Deployments overview — the managed-cloud path.
Data governance — the row, column and masking rules that travel inside the bundle.