Install on AWS

Stand up Definite in your own AWS account: EKS, RDS, S3, all driven by Terraform and the definite CLI.

This guide walks you through a production-grade on-prem install of Definite on AWS. You'll provision the infrastructure with Terraform, install the platform with the definite CLI, and tear it down cleanly when you're done.

By default, the install uses Definite-brokered DNS and TLS. Definite provides a URL like https://<slug>.onprem.definite.app during setup, so you do not need to configure Route 53 or any other customer DNS before the first successful install.

End to end: about 30 to 40 minutes, most of which is terraform apply waiting on EKS and RDS.

What gets created

Prerequisites

Phase 1: Provision AWS infrastructure with Terraform

Download the AWS Terraform module from the public release bucket and unpack it:

curl -fsSL https://storage.googleapis.com/definite-public/definite-onprem/latest/terraform-aws.tar.gz -o terraform-aws.tar.gz
curl -fsSL https://storage.googleapis.com/definite-public/definite-onprem/latest/terraform-aws.tar.gz.sha256 | shasum -a 256 -c -
tar -xzf terraform-aws.tar.gz
cd definite-aws-terraform

To pin a specific release, replace latest with a version tag (for example v0.0.11).

1. Configure inputs

Copy the example tfvars file and edit it:

cp terraform.tfvars.example terraform.tfvars
$EDITOR terraform.tfvars

A minimal terraform.tfvars is just two lines:

region      = "<your-region>"
name_prefix = "<your-name-prefix>"

Everything else has a default. Common overrides:

# Lock the EKS public API endpoint to your office or VPN CIDRs.
cluster_endpoint_public_access_cidrs = ["<your-cidr>/24"]

# Production hardening.
rds_multi_az            = true
rds_deletion_protection = true

# Bedrock model access (must be enabled in the AWS console first).
# Use current (non-Legacy) model IDs available in YOUR region.
bedrock_model_ids = ["anthropic.claude-sonnet-4-6"]

See the README.md included in the module for the full list of variables.

2. Init, plan, apply

terraform init
terraform plan
terraform apply

terraform apply takes 20 to 25 minutes (mostly EKS and RDS). When it finishes, every value you need is in terraform output.

3. Read the outputs

Inspect the non-sensitive outputs:

terraform output

For sensitive values, read them explicitly with -raw:

terraform output -raw rds_password
terraform output -raw lakehouse_s3_secret_access_key
terraform output -raw postgres_url

The values you'll feed into config.yaml are summarized here:

The module also emits a ready-to-paste, non-secret config.yaml snippet:

terraform output -raw config_yaml_fragment

IRSA vs access key

The module emits both an IRSA role and an IAM user + access key for lakehouse S3 access. Both share one identical least-privilege policy.

Fi's Bedrock access uses IRSA today (no static credentials).

Phase 2: Install Definite with the definite CLI

1. Install the CLI

curl -fsSL https://storage.googleapis.com/definite-public/definite-onprem/install.sh | sh

The install script detects your OS and architecture, downloads the matching prebuilt binary from a public Google Cloud Storage bucket, verifies its SHA256 checksum, and places definite on your PATH (default: $HOME/.local/bin). Binaries are published for macOS and Linux (arm64 and x86_64), and are uploaded by the release workflow using short-lived Workload Identity Federation credentials (no long-lived keys).

To pin a version, set DEFINITE_VERSION before piping to sh:

curl -fsSL https://storage.googleapis.com/definite-public/definite-onprem/install.sh \
  | DEFINITE_VERSION=v0.0.11 sh

Verify:

definite version

2. Point kubectl at the new cluster

aws eks update-kubeconfig \
  --region "$(terraform output -raw region)" \
  --name   "$(terraform output -raw cluster_name)"

kubectl get nodes

You should see your managed node group's nodes in the Ready state.

3. Bootstrap cluster prerequisites

definite bootstrap installs the cluster-level pieces that definite init assumes are already present:

Run it once against the fresh cluster:

definite bootstrap

--dry-run prints what it would install without touching the cluster. The command is idempotent; safe to re-run.

4. Let definite init request Definite-brokered DNS

The ingress controller provisions an AWS Network Load Balancer. Wait for it to land, then grab its hostname:

LB_HOST=$(kubectl get svc ingress-nginx-controller -n ingress-nginx \
  -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'
)
echo "$LB_HOST"

You'll get something like <random-id>.elb.<your-region>.amazonaws.com.

For the default path, do not stop here to ask the customer to create a CNAME. definite init calls the Definite setup broker for you, using the ingress target above. The backend contract is POST /onprem/v1/setup-sessions, but users and agents should not run a direct curl by default.

definite init --config config.yaml --dns-mode definite-brokered

The CLI returns a URL like:

https://<slug>.onprem.definite.app

5. Build config.yaml

Start from the EKS example config: minimal-eks.yaml. The shape:

deployment:
  name: definite
  namespace: definite
  dns_mode: definite-brokered

broker:
  # Optional. Omit for the default AWS path: definite init uses the active AWS
  # credential chain to acquire a short-lived setup token automatically.
  # setupToken:
  #   env: DEFINITE_ONPREM_SETUP_TOKEN

postgres:
  url: postgres://<rds-user>:${POSTGRES_PASSWORD}@<rds-endpoint>:5432/<db-name>

object_store:
  type: s3
  bucket: <bucket-name>              # terraform output lakehouse_bucket_name
  region: <your-region>              # terraform output region
  credentials:
    key_id:
      env: S3_ACCESS_KEY_ID
    secret:
      env: S3_SECRET_ACCESS_KEY

lakehouse:
  prefix: lake/                      # terraform output lakehouse_prefix
  storage:
    size: 50Gi
    storage_class_name: gp3

auth:
  mode: oidc                         # or `local` for username/password auth
  issuer: https://<your-okta-domain>
  client_id: definite-onprem
  client_secret:
    env: OIDC_CLIENT_SECRET

llm:
  provider: bedrock
  region: <your-region>
  model: anthropic.claude-sonnet-4-6   # current, non-Legacy model in your region
  # Credentials via IRSA; no credentials block needed.
  # Non-US regions: the bedrock provider path may not resolve non-`us.` profiles;
  # see "Non-US regions: route Fi through the LiteLLM proxy" below.

resources:
  api:
    replicas: 2
    cpu: "1"
    memory: 2Gi
  lakehouse:
    replicas: 1
    cpu: "4"
    memory: 16Gi
  frontend:
    replicas: 2
    cpu: 500m
    memory: 512Mi
  job_runner:
    replicas: 1
    cpu: 500m
    memory: 1Gi

For the full list of knobs (image registry overrides, ingress class, sandbox configuration, etc.), see the config reference in Definite's built-in docs, available in-product once your deployment is running.

6. Export secrets

config.yaml references env vars for every secret. Export them from Terraform outputs:

export POSTGRES_PASSWORD=$(terraform output -raw rds_password)
export S3_ACCESS_KEY_ID=$(terraform output -raw lakehouse_s3_access_key_id)
export S3_SECRET_ACCESS_KEY=$(terraform output -raw lakehouse_s3_secret_access_key)
export OIDC_CLIENT_SECRET=...        # only if auth.mode: oidc

Do not export LICENSE_KEY or DEFINITE_ONPREM_SETUP_TOKEN for the default brokered flow. definite init obtains the setup token and license from Definite after proving control of the active AWS credentials.

7. Preflight with definite doctor

definite doctor --config config.yaml

doctor runs a battery of preflight checks: it connects to Postgres and runs SELECT version(), validates the Kubernetes context, checks object-store config shape, and (for Anthropic) pings the LLM API. Fix anything it flags before moving on.

8. Deploy with definite init

definite init --config config.yaml

init re-runs preflight, renders the bundled Helm chart with your values, and runs helm upgrade --install. It waits for pods to reach Ready by default. Useful flags:

Watch the rollout in another terminal:

definite status --config config.yaml
definite logs api --follow

9. Set the initial admin user

The chart does not auto-create an initial admin. After definite init returns successfully and the pods are Ready, set INITIAL_ADMIN_EMAIL and INITIAL_ADMIN_PASSWORD on the api Deployment; the api creates the admin record on its next start.

ADMIN_PASSWORD=$(openssl rand -base64 24 | tr -dc 'A-Za-z0-9' | head -c 24)
kubectl set env deploy/definite-api -n definite \
  INITIAL_ADMIN_EMAIL=<your-email> \
  INITIAL_ADMIN_PASSWORD="$ADMIN_PASSWORD"
kubectl rollout status deploy/definite-api -n definite
echo "Admin password: $ADMIN_PASSWORD"

Save the password somewhere safe (1Password, Vault, etc.).

When the brokered URL reports DNS/TLS ready, open https://<brokered-hostname> in a browser and log in with the admin email and password from above.

Bedrock IRSA

If you're using Bedrock as the LLM provider (the default for AWS), Fi authenticates to Bedrock via IRSA: the pod's ServiceAccount must carry an eks.amazonaws.com/role-arn annotation pointing at the IRSA role Terraform created. There is no API key for Bedrock; the coding agent resolves credentials from the AWS credential chain (the projected web-identity token from IRSA, plus a region).

Confirm the annotation after definite init, and apply it if it is missing:

BEDROCK_ROLE_ARN=$(terraform output -raw bedrock_irsa_role_arn)

kubectl annotate serviceaccount definite -n definite \
  eks.amazonaws.com/role-arn="$BEDROCK_ROLE_ARN" --overwrite

# Restart the api pod so it picks up the projected token for the new role.
kubectl rollout restart deploy/definite-api -n definite
kubectl rollout status  deploy/definite-api -n definite

A subsequent definite upgrade preserves the annotation (Helm's three-way merge leaves unmanaged fields alone), but re-apply it if anyone does a helm uninstall + reinstall.

Choosing a Bedrock model and inference profile

Bedrock Claude access goes through a cross-region inference profile, not the bare foundation model ID. Inference profiles are prefixed by geography:

You must use the prefix that matches your region. The Terraform module and the bundled Helm chart default to us. everywhere, which only works in US regions. In other regions a us. profile either doesn't exist or the bare foundation ID is rejected with on-demand throughput isn't supported. Pick the profile prefix for your geography and a current (non-Legacy) model ID, for example:

# terraform.tfvars — example for ap-southeast-2 (Sydney)
bedrock_model_ids = [
  "anthropic.claude-sonnet-4-6",
  "anthropic.claude-opus-4-7",
  "anthropic.claude-sonnet-4-5-20250929-v1:0",
  "anthropic.claude-haiku-4-5-20251001-v1:0",
]

Non-US regions: route Fi through the LiteLLM proxy

The Fi sandbox client (@earendil-works/pi-ai) normalizes Bedrock model IDs before calling Bedrock, and today it only understands two shapes: a us.-prefixed profile ID (passed through), or an anthropic.-prefixed foundation ID (it prepends us.). Any other prefix, including au., eu., and apac., gets mangled (au.anthropic.claude-sonnet-4-6 becomes us.anthropic.au.anthropic.claude-sonnet-4-6) and Fi fails with:

Run failed - failed to publish Pi events: Validation error:
The provided model identifier is invalid.

You may also see this surface earlier as No API key found for amazon-bedrock. Use /login ... from /opt/fi-agent/..., which is the agent's generic fallback when it can't resolve a usable Bedrock target.

Until the sandbox client handles non-US prefixes natively, the working path for non-US regions is to point Fi at the bundled LiteLLM proxy (the definite-litellm deployment), which does the model mapping and Bedrock auth for you. This is an advanced, manual path:

1. Switch the chart to the litellm provider. The definite CLI's config.yaml only accepts provider: anthropic | bedrock | vertex | azure_openai, so you can't select LiteLLM through the CLI. Apply it with a direct Helm override instead:

# litellm-override.yaml
llm:
  provider: litellm
  model: claude-sonnet-4-6
  region: ap-southeast-2
  litellmUpstream: bedrock
  litellmImage: "ghcr.io/berriai/litellm:main-v1.82.0-stable"
  apiKey: "<LITELLM_MASTER_KEY>"     # see step 3

helm upgrade definite ~/.cache/definite/chart-<version> -n definite \
  --reuse-values -f litellm-override.yaml

2. Patch the LiteLLM ConfigMap to your region's profile IDs. The chart ships definite-litellm-config hardcoded with us.* model IDs, so edit definite-litellm-config to map each model_name to the correct bedrock/<prefix>.anthropic.... target and aws_region_name, then restart the proxy:

kubectl edit configmap definite-litellm-config -n definite
# e.g. claude-sonnet-4-6 -> bedrock/au.anthropic.claude-sonnet-4-6, aws_region_name: ap-southeast-2
kubectl rollout restart deployment/definite-litellm -n definite

3. Set a LiteLLM master key. With the bedrock provider the llm-api-key entry in definite-secrets is empty (Bedrock uses IRSA, not a key). LiteLLM needs one, so generate a key, reference it as LITELLM_MASTER_KEY (general_settings.master_key), and patch it into definite-secrets.

The path that should work end to end once configured is: Fi sandbox → definite-litellm (port 4000) → Bedrock. Smoke-test it from inside the cluster:

kubectl run llm-smoke --rm -it --image=curlimages/curl -n definite --restart=Never -- \
  curl -s http://definite-litellm.definite.svc.cluster.local:4000/v1/chat/completions \
  -H "Authorization: Bearer <LITELLM_MASTER_KEY>" -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4-6","messages":[{"role":"user","content":"say Ready"}]}'

Day-2 operations

The same CLI handles upgrades, logs, license, and lakehouse maintenance. A few of the most common commands:

definite status   --config config.yaml         # `kubectl get pods,svc,ingress` for the namespace
definite logs api --follow                     # stream component logs
definite upgrade  --config config.yaml         # re-render and re-apply with the current CLI version
definite license  status                       # show the deployment's live plan + activation status
definite run maintenance stats                 # lakehouse file/snapshot stats

Definite's built-in docs include a full CLI reference for every command and flag.

Phase 3: Teardown

First, delete the orphaned NLB so Terraform can clean up the VPC:

VPC=$(terraform output -raw vpc_id)
LB_ARN=$(aws elbv2 describe-load-balancers \
  --query "LoadBalancers[?VpcId=='$VPC'].LoadBalancerArn" --output text)
[ -n "$LB_ARN" ] && aws elbv2 delete-load-balancer --load-balancer-arn "$LB_ARN"

Wait 30 to 60 seconds for the ENIs to clear, then destroy the rest with Terraform:

cd definite-aws-terraform
terraform destroy

A couple of safety rails are on by default:

For production teardowns, snapshot RDS and back up the S3 bucket first; once Terraform deletes them, they're gone.

Troubleshooting

Next steps

• Connect a data source to start ingesting data.
• Set up the MCP server so Claude, Cursor, or Windsurf can query your deployment.
• For deeper config (custom container registry, sandbox network policies, OIDC tuning), see the config reference in Definite's built-in docs.

Support

For issues or questions, contact hello@definite.app.