Deploy on AWS VM

This is the simplest, most cost-effective way to deploy Sema4.ai on AWS, with infrastructure dependencies kept to a minimum. The application installs onto a single Linux EC2 instance — it brings its own Kubernetes runtime and admin console. It's suitable for small-scale production use.

If your team runs Kubernetes, AWS EKS is usually the better fit. Customers with stricter governance or compliance requirements can work with Sema4.ai to design a tailored architecture. A reference Terraform module (opens in a new tab) is available for AWS.

The infrastructure in the bill of materials moves at the speed of your procurement, network, IAM, and security teams. The Sema4.ai install itself is under 90 minutes, and a POC can run the same day.

Part 1 — Pre-deployment bill of materials

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

Decide these carefully — they're painful to retrofit:

Hostname — TLS, OIDC redirect URIs, and ingress all derive from it; changing it later means re-issuing certs and reconfiguring your IdP.
Region — moving regions later means a rebuild.
Private connectivity for RDS, S3, and KMS — for anything beyond a POC, plan VPC endpoints / private subnets on day 1.

Components

Category	Component	Spec / SKU	Notes
Compute	EC2 instance	4 vCPU, 16 GiB RAM, ≥100 GiB gp3 EBS, Ubuntu 24.04 LTS (e.g. `m7i.xlarge`)	Hosts the full stack: app, agent data server, Caddy ingress
Network	DNS record	An A record for the workspace, e.g. `sema4-agents.<customer>.com` → the instance IP	TLS, OIDC redirect, and ingress all depend on it. Confirm you can edit DNS first
Network	TLS termination	Public IP: Let's Encrypt via Caddy on the instance (TLS-ALPN-01, no extra AWS resource). No public IP: provide your own TLS termination or a custom cert + key	Customer cert only needed for the ALB / CloudFront alternative
Network	VPC + subnet	New or existing	Security group rules per the rows below
Network	Security group (inbound)	HTTPS line of sight for end users and API clients; SSH for instance management
Data	PostgreSQL	Amazon RDS for PostgreSQL (or Aurora PostgreSQL), PG 17+, reachable from the instance	Private access from the VM's subnet recommended. The app creates its schema on first boot and enables the `uuid-ossp` and `plpgsql` extensions itself, so its database user must be able to run `CREATE EXTENSION`. Capture host, port, admin credentials, and database name
Data	S3 bucket	A bucket reserved for the deployment (a configurable key prefix lets multiple deployments share one bucket)	Restrict access to the VM via its IAM role and a bucket policy. Stores agent files, uploads, exports, artifacts
Data	KMS key	An AWS KMS key (`SYMMETRIC_DEFAULT`, key usage Encrypt and decrypt)	Envelope encryption of secrets at rest. You provide the key ARN at install. Not for storing app secrets
Identity	OIDC IdP app	App registration in Entra ID / Okta / Auth0 with redirect URI `https://<hostname>/oidc/login/callback`, scopes `openid profile email`, group claims if access-restricted	Discovery URL, Client ID, and Client Secret needed at install. See Identity providers (OIDC)
Identity	IAM instance role	An IAM role (instance profile) attached to the EC2 instance	Grants the application access to the S3 bucket and `Encrypt` / `Decrypt` / `GenerateDataKey` on the KMS key — no static access keys needed
Access	AWS access	Suitable AWS permissions on the account/region for the deploying administrator	Just-in-time access acceptable
Access	Admin SSH access	An SSH keypair for the instance admin account; the admin user has `sudo`	Required for install and day-2 maintenance
Egress	Outbound HTTPS	Unrestricted egress recommended. Needed to reach the Sema4.ai services, Let's Encrypt ACME, Ubuntu package mirrors, plus your LLMs and MCP servers	See the network endpoints for the Sema4.ai hosts, and Add networking rules

Alternative ingress (advanced)

The default public-IP path uses Caddy on the instance with Let's Encrypt. You can substitute an Application Load Balancer or CloudFront (with a certificate from AWS Certificate Manager) for a managed front end, a non-internet-facing instance, or integrated certificate lifecycle.

If you need a non-default ingress, contact Sema4.ai before provisioning — we'll review the target architecture and adapt the install.

Part 2 — Deployment steps

Step 1: Pick the hostname (foundational)

Decide the public hostname (e.g. finance-agents.company.com) on a domain you control, and confirm you can create and update its DNS records. TLS, the OIDC redirect URI, and the cluster ingress all derive from it — changing it later means re-issuing certificates, updating your IdP, and reconfiguring the cluster.

Step 2: Decide network architecture

Public, internet-accessible: an instance with a public IP, port 443 reachable from the internet, Caddy terminating TLS via Let's Encrypt (TLS-ALPN-01).
Non-public IP: if you require an alternative front end (ALB, CloudFront + a private instance), see Alternative ingress and contact Sema4.ai before provisioning.

Step 3: Register the OIDC application

Register an OIDC application in your identity provider and capture the Discovery URL, Client ID, and Client Secret you'll enter at install. Use:

Redirect URI: https://<hostname>/oidc/login/callback
Scopes: openid, profile, email
Authorization code flow with PKCE where supported; restrict to the allowed group(s) if your IdP supports it.

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

Step 4: Provision AWS infrastructure

Either apply the reference Terraform for AWS (opens in a new tab), or provision yourself using the bill of materials as the spec. The end state must include:

PostgreSQL 17+ (RDS or Aurora) with the uuid-ossp and plpgsql extensions available, reachable from the instance; capture host, port, admin credentials, and database name.
An S3 bucket for the deployment (note any key prefix).
A KMS key (SYMMETRIC_DEFAULT, Encrypt/decrypt); capture its ARN.
An EC2 instance matching the bill of materials, with an IAM instance role attached granting access to the S3 bucket and the KMS key.

Step 5: Configure DNS and confirm

Create the A record from Step 1 pointing to the instance's static IP (an Elastic IP), then confirm resolution:

dig +short <hostname>
# Expected: <instance-ip>

Do not proceed until dig +short <hostname> returns the instance's IP.

Step 6: Install the application

Sema4.ai ships as a Replicated KOTS application installed into an embedded single-node Kubernetes cluster on the instance.

6.1 Get the install command

Open the Sema4.ai Enterprise portal (opens in a new tab) and sign in with the email on your license (you'll get a one-time verification code).
Select your application and copy the install command for the latest release.
SSH into the instance (if using the reference Terraform, get the command from its output).
Run the install command with sudo. On smaller instances, host preflight checks may fail — they can be skipped with --ignore-host-preflights.
When prompted, set the admin-console password and keep it safe — you'll need it for configuration changes and software updates.

6.2 Open the admin console via SSH tunnel

The admin console isn't exposed to the internet. Open an SSH tunnel forwarding localhost:8800 → admin port :30000 on the instance (the reference Terraform outputs this command):

ssh -i ~/.ssh/s4admin-privatekey.pem -L 8800:localhost:30000 s4admin@<hostname>

6.3 Configure the deployment

Browse to https://localhost:8800, accept the self-signed certificate, sign in with the admin password, accept the license, and choose Single node topology. Then fill in the config screen:

External URL containing the hostname
Service type (Networking): select Built-in TLS termination if the instance is exposed directly to the internet
Postgres host, port, admin credentials, database name
OIDC — choose OIDC Generic and enter the discovery URL, client ID, and client secret
Infrastructure platform: Amazon Web Services
S3 bucket name and optional key prefix
KMS key ARN
Observability platform (Datadog supported, otherwise None)

6.4 Deploy

Click Deploy. The first deploy takes 5–15 minutes while the embedded cluster pulls images, runs migrations, and provisions the Let's Encrypt certificate.

Step 7: Validate

Browse to https://<hostname> — login should redirect to your IdP.
Sign in with a permitted user; you should land in the Sema4.ai workspace.
Run a smoke-test agent to confirm the data plane (Postgres, S3).

Next steps

With the application running, continue to First-time setup to connect LLMs, set up MCP OAuth, and configure the rest of the workspace.

AWS EKS Azure AKS