Architecture - Polyaxon

Overview

Polyaxon is a decoupled platform split into two planes:

A control plane that holds state, exposes the API, compiles and schedules operations, and serves the UI, logs, and artifacts.
An execution plane of one or more Kubernetes clusters where Agents run the actual workloads.

The two planes communicate asynchronously, so submission spikes never block the API, and a single control plane can drive workloads across multiple clusters, namespaces, and resource pools.

Control plane

The control plane is the stateful core. It runs independently of where workloads execute.

Gateway — the entry point for all platform traffic: API requests, reverse proxying, artifact streaming, service access, sandbox routes, and the AI gateway for LLM calls. It keeps user-facing access separate from the agents and Kubernetes resources that execute the work.
API — a self-consuming RESTful JSON API that backs the UI, CLI, SDKs, generated clients, and webhooks. Every surface goes through the same API.
Compiler — validates and compiles operations (Polyaxonfiles) into concrete runtime specs, resolves inputs, outputs, connections, and dependencies, and places work in queues.
Scheduler — coordinates queued work with Agents asynchronously over Redis. Submission load is absorbed by the queue instead of blocking the API.
Workers — Celery workers handle background tasks: event handling, notifications, automation, cleanup, and migrations, with configurable concurrency and prefetch.
Streams — serve logs and artifacts. Large files move directly between the client SDKs and object storage, keeping the API lightweight.

Execution plane

Agents — deployed on each Kubernetes cluster. They poll the control plane for work and manage workloads locally, so the control plane never needs direct access to the execution clusters. This is what enables multi-cluster deployments and isolation between the two planes.
Operator — a Kubernetes operator that reconciles Polyaxon operations into the underlying Kubernetes resources (jobs, services, distributed and Kubeflow operator workloads) and reports status back.

Queues, presets, namespaces, resource requests, node placement, service accounts, and security context decide where each workload runs and what it can access.

State and dependencies

Polyaxon depends only on open source components:

PostgreSQL — operations, tracking events, and metadata, with transactional guarantees.
Redis — caching (including API keys and agent tokens, so the database is not hit on every call) and the Celery broker and result backend.
Object storage — S3, GCS, Azure Blob, or NFS for artifacts, logs, and model files.
Connections — container registries, artifact stores, Git providers, secrets, and other external systems wired in through connection objects.

Interfaces

Polyaxon runs in the cloud or on-premise and is reachable from:

The dashboard (UI).
The command line interface.
SDKs and generated clients targeting the API.
Webhooks and the REST API for headless and automated use.

These interfaces share the same API and platform logic — notebooks, CI jobs, local terminals, internal dashboards, and production services all drive the same operations.

What Polyaxon manages

On top of Kubernetes — which handles cluster resources (CPU, GPU, TPU, memory), repeatable deployments, and scaling — Polyaxon does the heavy lifting of:

Exposing a rich runtime: jobs, services, distributed and Kubeflow operator workloads, notebooks, dashboards, and sandboxes.
Scheduling operations and resolving dependencies between them.
Automation through a flow engine (DAGs) and an optimization engine (hyperparameter search).
An AI gateway for LLM traffic, with provider routing, credentials, and usage tracking.
Building container images for workloads.
Validating and authorizing access to resources, connections, and namespaces.
Monitoring statuses and resource usage, and streaming logs.
Tracking code versions, params, metrics, configs, artifacts, and tags.
Application tracing and evaluations for LLM applications and agents.
Versioning models, artifacts, components, and prompts in registries.
Driving insights, comparisons, and analytics across runs.

Because the components are decoupled, there is room for customization. Teams can deploy only the core and use an external tracking service, or replace the built-in scheduler, flow engine, or optimization engine with other platforms. The event/action interface lets you alter internal behavior — for example, building your own scheduler.

For deployment, scaling, and the performance and reliability internals of each component, see the deployment guide and platform setup. For the full capability list, see features.