Deploy on AWS EKS

Install a self-hosted deployment into your own AWS account, on an EKS cluster with a sandbox-capable node.

Audience: IT (the enabler)

This guide assumes you are comfortable operating EKS. It does not cover general Kubernetes administration.

Before you start, read Cluster and node requirements. The cluster this guide builds is not a generic one, and the node preparation it describes is the part most likely to catch you out.

A reference Terraform configuration provisions the whole shape: the VPC, the EKS cluster and its add-ons, the database, the bucket and key, and the prepared application node. Use it unless you have a reason not to.

Part 1: Pre-deployment bill of materials

Hand this to procurement and your cloud and security teams on day 0.

Decide these carefully, they are painful to retrofit:

Hostname. TLS, the OIDC redirect URI, and ingress all derive from it. Changing it later means re-issuing certificates and reconfiguring your identity provider.
Region. Moving regions later means a rebuild.

Components

Category	Component	Spec	Notes
Compute	EKS cluster	EKS 1.36 or newer, with the cluster add-ons the platform depends on	See Cluster and node requirements
Compute	Application node	A single x86_64 `m8i` or `m8i-flex` instance with nested virtualization explicitly enabled, labeled as the application node. Minimum 16 vCPU and 64 GiB, recommended 32 vCPU and 128 GiB	Hosts the application and every sandbox run. Not interchangeable with a general-purpose node group. See Node sizing
Storage	Node root volume	Encrypted gp3	Sized for the node image and container images
Storage	Node data volume	A separate encrypted gp3 volume, formatted btrfs during node bootstrap	A cache for materialized workspaces and sandbox images, not a system of record. Deleted with the node by design
Network	VPC and subnets	Private subnets across multiple availability zones, with NAT for egress	The reference Terraform provisions a dedicated VPC
Network	Cluster ingress	An ALB fronting the application, with an issued ACM certificate in the same region	You operate the ingress and terminate TLS there
Network	DNS record	Your chosen hostname resolving to the ingress endpoint
Data	PostgreSQL	Aurora PostgreSQL Serverless v2, private only	Primary application data store
Data	S3 bucket	A bucket for the deployment, with a customer-managed KMS key	Durable storage for files, artifacts, and the workspace filesystem. Materialized onto the node on demand
Data	KMS key	Customer-managed, with rotation enabled	Envelope encryption of secrets at rest
Identity	OIDC IdP app	An application registered in Entra ID, Okta, or Auth0	See Identity providers (OIDC)
Access	AWS and EKS admin access	Permissions for the deploying administrator, plus `kubectl`, `helm`, and `terraform` on their workstation	EKS access entries must reference stable IAM role or user ARNs
Egress	Outbound HTTPS	Unrestricted egress recommended	Needed for the Sema4.ai services, the sandbox runtime download during node bootstrap, and everything you connect the platform to. See Network endpoints

Node sizing

The application node carries the whole platform and every concurrent sandbox run, so size it for both. Sandbox concurrency is a fixed runner pool rather than something that autoscales, which makes the node the hard ceiling on how much agent work can run at once.

There are two supported sizes:

Spec	vCPU	Memory	Instance type	Suits
Minimum	16	64 GiB	`m8i.4xlarge`	A small workspace: a single team, a handful of Apps, light concurrent agent work
Recommended	32	128 GiB	`m8i.8xlarge`	A medium workspace: several teams sharing the platform, with headroom for concurrent sandbox runs

The minimum is a supported production size, not a proof-of-concept tier. Pick it when your workspace is genuinely small. Pick the recommended size when you expect several teams on the platform, or when sustained concurrent agent work matters more to you than instance cost.

Budget for the gap between instance size and what you actually get. Cluster add-ons and system DaemonSets take their share first, so a 16 vCPU / 64 GiB node lands near 15 vCPU and 59 GiB allocatable, and the platform's own baseline requests come out of that before the first sandbox run starts. Sizing against allocatable capacity is what keeps the runner pool from being squeezed.

This release does not scale horizontally, so the node you pick is the ceiling for the life of the deployment. Sizing up later means replacing the node, which costs downtime and a cold cache rather than data. If you expect to outgrow the minimum within the year, start at the recommended size. See Caveats and limits.

Part 2: Deployment steps

Step 1: Pick the hostname

Choose the hostname on a domain you control, for example finance-agents.company.com. Whether it resolves publicly or only inside your network is your choice. TLS, the OIDC redirect URI, and the ingress configuration all derive from it. You point DNS at the ingress in Step 6.

Issue an ACM certificate for the hostname in the same region as the cluster, and confirm it reaches Issued before you provision.

Step 2: Register the OIDC application

Register an OIDC application in your identity provider and capture the Discovery URL, Client ID, and Client Secret.

Configure it with:

Callback URL: https://<hostname>/api/v1/auth/callback
Logout URL: https://<hostname>
Application login URI: https://<hostname>/login
Allowed web origin: https://<hostname>
Scopes: openid, profile, email

Follow the guide for your provider: Microsoft Entra ID · Auth0 · Okta.

Step 3: Provision AWS infrastructure

Apply the reference Terraform, or provision yourself using the bill of materials as the spec. The end state must include:

An EKS cluster with the required add-ons, and kubectl access configured against it.
The application node, with nested virtualization enabled and both volumes attached.
Aurora PostgreSQL, reachable from the cluster.
An S3 bucket and a KMS key.
An ALB ingress and the ACM certificate from Step 1.

The Terraform provisions the node so that its bootstrap installs the sandbox runtime and prepares the data volume before the node joins the cluster.

Step 4: Confirm node preparation succeeded

Do not skip this. A node that joined without preparation looks healthy and cannot run agent work.

Confirm that:

The node is Ready and carries the application node label.
The sandbox runtime class exists in the cluster.
Node bootstrap wrote its completion marker.
The data volume is mounted btrfs at the data root, with shared propagation.

If the node never becomes ready, read its console output. Bootstrap reports the failing stage there.

Step 5: Install the application

The self-hosted release channel for version 3 is not open yet. There is no install command to publish. This step will carry the registry login and the chart install once the channel ships.

Step 6: Point DNS at your ingress

Create the DNS record resolving your hostname to the ALB endpoint. Sign-in does not complete until the hostname resolves and TLS is serving.

Step 7: Validate

Browse to https://<hostname>. Sign-in should redirect to your identity provider.
Sign in with a permitted user and confirm you land in the workspace.
Run a smoke test that exercises a sandboxed run, which confirms the node preparation, the database, and object storage together. Expect the first run to be slower than steady state while the node's caches fill.

The first user of a new deployment becomes its owner. Sign in yourself first, before opening access more widely.

Next steps

With the application running, continue to Administration to configure models, connect integrations and data sources, and set up teams.

What this article will cover

The exact Terraform inputs and a worked terraform.tfvars
The full bill of materials with concrete sizes, versions, and SKUs
The install commands, once the self-hosted channel ships
Screenshots of the install flow
Upgrading an existing deployment
Replacing the application node, and what a cold start looks like
Teardown, and what survives it

Cluster and node requirements Identity providers (OIDC)