Requirements - Aperium Docs

This page lists every runtime and external service Aperium relies on, marked as required or optional. Once you’ve decided what to run, see Environment variables for the exact settings that wire each one up.

Runtimes

Python >=3.12,<3.15 with the uv package manager. Used to run the backend.
Node.js 20 or newer with the pnpm package manager. Used to build and serve the frontend.
Docker / OCI runtime. All production deployments ship as container images.

Aperium ships as two images. The backend is a single multi-stage image that serves the API, worker, embeddings, and migrations from one build (it exposes ports 8010, 8090, and 8091, with models baked in for offline operation). The frontend is a separate image built from the UI workspace and served behind its own web server. Deploy both together.

Orchestration runs on Temporal. Production has fully moved to Temporal for background jobs, scheduled tasks, and document workflows. The bundled reference-infra deployment package still provisions Prefect — it predates the cutover — so the Prefect steps in the GCP pages below are legacy and pending an infra update. Deploy Temporal for orchestration; treat the Prefect scaffold as transitional.

Core services

These are required for any production deployment.

Service	Required	Used for	Configured via
PostgreSQL (16 or newer)	Yes	The application database: tenants, users, agents, conversations, integration credentials, and the `tabular` schema for spreadsheet data. SQLite is no longer supported.	Database
At least one LLM provider	Yes	Calling Claude (or another supported model) for the agent loop. Pick Anthropic API or AWS Bedrock. Both can be enabled side by side.	LLM providers
OIDC identity provider	Yes	Single sign-on. Aperium supports Okta, Auth0, Microsoft Entra ID, and any other standards-compliant OIDC provider via the multi-tenant `AUTH_TENANTS_JSON` config.	OIDC tenant config (see your IdP’s docs and the auth section of `backend/.env.example`)
MCP credential encryption key	Yes	A 32-byte base64-encoded key used to encrypt every tenant integration credential at rest. Generate one per environment and treat it as a master secret.	MCP runtime
Redis (7 or newer)	Yes	Cross-pod WebSocket pub/sub, shared session state, agent config caching, and rate limiting. Required for any deployment running more than one backend pod, which is the default for production.	Multi-pod and Redis
Object storage or shared file storage	Yes (one of the two)	A place to store uploaded files. Choose either a Google Cloud Storage bucket or a shared RWX volume mounted into every backend pod.	File uploads and shared storage

Recommended services

These aren’t strictly required to boot the app, but production deployments should plan to run them.

Service	Required	Used for	Configured via
Qdrant	Strongly recommended	Vector store for agent memories, document chunks, the experience library, workflow patterns, and tool semantic routing. Anything that uses retrieval, memory, or semantic tool selection needs this.	Vector database (Qdrant)
SMTP server	Recommended	Outbound email for invites, share notifications, and password resets.	Email (SMTP)
Temporal	Required for production	Durable orchestration for background jobs, scheduled tasks, and document workflows — the agent-intelligence scheduler and daily brief run on it. Production has moved off Prefect; the reference-infra package still ships a Prefect scaffold pending update.	Temporal service (self-hosted or Temporal Cloud)
Tabular query backend	Yes (PostgreSQL or BigQuery)	Backs the spreadsheet/CSV analytics feature. Most deployments use the same PostgreSQL instance as the application database; BigQuery is supported as an alternative when you already have data warehoused there.	Tabular query backend
LibreOffice render service	Recommended	A small in-cluster HTTP service that recalculates Excel formulas and renders spreadsheet output. Most deployments need this because document and dashboard workflows commonly generate or rewrite Excel files.	`LIBREOFFICE_SERVICE_URL` (see on-prem Configuration)

Optional services

Each of these gates a specific feature. Skip the ones you don’t need.

Service	Required	Used for	Configured via
OpenTelemetry collector + Phoenix	Optional	Trace collection and visualization for the agent loop and tool calls. Without this, the backend still runs but you lose first-class tracing.	Tracing and observability
Sentry	Optional	Backend error tracking and performance monitoring.	Sentry
GCP Cloud Profiler	Optional	CPU and memory profiling for GCP-hosted backends.	`ENABLE_GCP_PROFILER` (see env reference)
Document worker pool	Optional	Dedicated worker pods for high-volume document processing. Without this, processing runs inline in the API pod.	`DOCUMENT_PROCESSING_MODE`, `DOCUMENT_WORKER_*` (see env reference)
Tensorlake	Optional	Cloud-hosted structured document extraction (tables, forms, complex PDFs) when the built-in document worker isn’t enough.	`TENSLAKE_API_KEY` and related env vars
Local LLM server	Required for on-prem with `ENABLE_LLM_FALLBACK=false`	An OpenAI-compatible inference server (vLLM, Ollama, Azure Foundry, or any other compatible endpoint) running inside your network boundary. Used when running fully on-prem without cloud LLM access.	On-prem Local LLM
GPU node pool	Required only when self-hosting the local LLM	Hosts the local model server in on-prem deployments.	On-prem overview
Secrets management	Recommended for production	A backing store for application secrets: GCP Secret Manager + External Secrets, HashiCorp Vault, Sealed Secrets, or any approved Kubernetes Secret pipeline. The MCP credential encryption key, database URL, and SMTP credentials all belong here.	GCP secrets for the GCP path; on-prem uses your chosen backend
Ingress + TLS + WAF	Yes for any externally reachable deployment	TLS termination on `/` and `/ws`, plus a WAF or firewall layer. On GCP this is GKE Gateway + Cloud Armor; on-prem it’s whatever your platform provides.	GCP overview, On-prem overview

Production prerequisites (GCP)

If you’re running the supported production deployment on Google Cloud, you also need:

A GCP project for the shared apps environment.
A Terraform Cloud / HCP Terraform organization and workspaces.
Authority to delegate the parent DNS zone to the managed apps.YOUR_DOMAIN subdomain.
A GitHub App that ArgoCD can use for repository access (App ID, installation ID, and private key).

For the full prerequisite list, see GCP prerequisites.

Where to set everything

Once you have the services running, point Aperium at them through env vars. Every variable is documented on the Environment variables page, grouped to match the sections above.

CPU, memory, and disk sizing: to be confirmed. Concrete minimum resource recommendations for the backend, frontend, and supporting services are not yet validated. Verify against your own load testing before sizing a production cluster.

​Runtimes

​Core services

​Recommended services

​Optional services

​Production prerequisites (GCP)

​Where to set everything

Runtimes

Core services

Recommended services

Optional services

Production prerequisites (GCP)

Where to set everything