Skip to content

Self-improving AI Employees for everyone

feat(deploy): add an AWS Terraform module for the validated t3.micro setup

trohitgbb631aadbdda
diff --git a/.gitignore b/.gitignore
index ccd88df5..44e03969 100644
--- a/.gitignore
+++ b/.gitignore
@@ -170,3 +170,6 @@ server/tests/_test_opencompany_root/
# Experiments (work in progress)
# =============================================================================
server/experiments/
+
+# Terraform provider cache (cli/terraform/*)
+**/.terraform/
diff --git a/cli/terraform/aws/.terraform.lock.hcl b/cli/terraform/aws/.terraform.lock.hcl
new file mode 100644
index 00000000..c900c1bd
--- /dev/null
+++ b/cli/terraform/aws/.terraform.lock.hcl
@@ -0,0 +1,25 @@
+# This file is maintained automatically by "terraform init".
+# Manual edits may be lost in future updates.
+
+provider "registry.terraform.io/hashicorp/aws" {
+ version = "5.100.0"
+ constraints = "~> 5.92"
+ hashes = [
+ "h1:H3mU/7URhP0uCRGK8jeQRKxx2XFzEqLiOq/L2Bbiaxs=",
+ "zh:054b8dd49f0549c9a7cc27d159e45327b7b65cf404da5e5a20da154b90b8a644",
+ "zh:0b97bf8d5e03d15d83cc40b0530a1f84b459354939ba6f135a0086c20ebbe6b2",
+ "zh:1589a2266af699cbd5d80737a0fe02e54ec9cf2ca54e7e00ac51c7359056f274",
+ "zh:6330766f1d85f01ae6ea90d1b214b8b74cc8c1badc4696b165b36ddd4cc15f7b",
+ "zh:7c8c2e30d8e55291b86fcb64bdf6c25489d538688545eb48fd74ad622e5d3862",
+ "zh:99b1003bd9bd32ee323544da897148f46a527f622dc3971af63ea3e251596342",
+ "zh:9b12af85486a96aedd8d7984b0ff811a4b42e3d88dad1a3fb4c0b580d04fa425",
+ "zh:9f8b909d3ec50ade83c8062290378b1ec553edef6a447c56dadc01a99f4eaa93",
+ "zh:aaef921ff9aabaf8b1869a86d692ebd24fbd4e12c21205034bb679b9caf883a2",
+ "zh:ac882313207aba00dd5a76dbd572a0ddc818bb9cbf5c9d61b28fe30efaec951e",
+ "zh:bb64e8aff37becab373a1a0cc1080990785304141af42ed6aa3dd4913b000421",
+ "zh:dfe495f6621df5540d9c92ad40b8067376350b005c637ea6efac5dc15028add4",
+ "zh:f0ddf0eaf052766cfe09dea8200a946519f653c384ab4336e2a4a64fdd6310e9",
+ "zh:f1b7e684f4c7ae1eed272b6de7d2049bb87a0275cb04dbb7cda6636f600699c9",
+ "zh:ff461571e3f233699bf690db319dfe46aec75e58726636a0d97dd9ac6e32fb70",
+ ]
+}
diff --git a/cli/terraform/aws/README.md b/cli/terraform/aws/README.md
new file mode 100644
index 00000000..f9163f22
--- /dev/null
+++ b/cli/terraform/aws/README.md
@@ -0,0 +1,41 @@
+# OpenCompany on AWS (Terraform)
+
+One login-gated EC2 instance running OpenCompany. File layout and workflow
+follow the HashiCorp AWS get-started tutorial
+(https://developer.hashicorp.com/terraform/tutorials/aws-get-started):
+`terraform.tf` (providers), `main.tf`, `variables.tf`, `outputs.tf`.
+
+Settings are the ones validated on a live t3.micro in September 2026:
+
+| Setting | Value | Why |
+|---|---|---|
+| Instance | `t3.micro`, 2 vCPU, 1 GiB | Smallest size the app runs on (backend ~200 MB + Temporal ~150 MB). 512 MB OOM-loops. |
+| Credit mode | `standard` | Caps compute at the hourly rate under continuous CPU load. |
+| Root disk | 10 GiB gp3, deleted with the instance | A fresh install uses ~4.5 GiB. |
+| Image | Ubuntu 24.04 LTS (Canonical) | Python 3.12 inside the server's `<3.13` pin; apt Node 18 is enough. |
+| Install | `install.sh` as `ubuntu`, no sudo | Root installs leave the venvs unusable by the login user (errors.md #16). |
+| Runtime | `company serve` under systemd as `ubuntu` | `AmbientCapabilities=CAP_NET_BIND_SERVICE` for port 80. |
+| Security group | 22, 80, 443 and the app port from `allow_cidr` | Same shape as the gcp module. |
+
+```bash
+cd cli/terraform/aws
+terraform init
+terraform fmt
+terraform validate
+terraform apply -var key_name=<your-key-pair> -var opencompany_version=0.1.1 \
+ -var-file=app_env.auto.tfvars.json
+terraform output url
+```
+
+`app_env` carries the owner login, fresh JWT/encryption keys, `PORT=80`,
+`DATA_DIR=/var/lib/opencompany` and `TEMPORAL_ENABLED=false`. Generate it with
+`cli/commands/deploy/_secrets.py build_app_env(owner_email=..., owner_password=...,
+port=80)` and write it as `{"app_env": {...}}` to `app_env.auto.tfvars.json`
+(gitignored) rather than typing it by hand. First boot takes 3 to 5 minutes.
+
+Uses the AWS CLI's default credential chain. `company deploy` cannot drive this
+module yet; it needs an AWS entry in `cli/commands/deploy/providers`.
+
+Cost at us-east-1 list prices: about $12/month fixed (instance, disk, public
+IPv4), and CPU load cannot raise it. Egress past the free 100 GB/month is the
+only open-ended line.
diff --git a/cli/terraform/aws/main.tf b/cli/terraform/aws/main.tf
new file mode 100644
index 00000000..c2fd2468
--- /dev/null
+++ b/cli/terraform/aws/main.tf
@@ -0,0 +1,73 @@
+provider "aws" {
+ region = var.region
+}
+
+# Ubuntu 24.04 LTS (Canonical): Python 3.12 is inside the server's
+# ">=3.11,<3.13" pin, so uv needs no managed download, and apt's Node 18 is
+# enough for install.sh.
+data "aws_ami" "ubuntu" {
+ most_recent = true
+
+ filter {
+ name = "name"
+ values = ["ubuntu/images/hvm-ssd-gp3/ubuntu-noble-24.04-amd64-server-*"]
+ }
+
+ owners = ["099720109477"] # Canonical
+}
+
+resource "aws_security_group" "app_server" {
+ name = "${var.instance_name}-app"
+ description = "OpenCompany: SSH, web, and the app port"
+
+ dynamic "ingress" {
+ for_each = toset(distinct([22, 80, 443, var.port]))
+ content {
+ from_port = ingress.value
+ to_port = ingress.value
+ protocol = "tcp"
+ cidr_blocks = [var.allow_cidr]
+ }
+ }
+
+ egress {
+ from_port = 0
+ to_port = 0
+ protocol = "-1"
+ cidr_blocks = ["0.0.0.0/0"]
+ }
+
+ tags = {
+ Name = "${var.instance_name}-app"
+ }
+}
+
+resource "aws_instance" "app_server" {
+ ami = data.aws_ami.ubuntu.id
+ instance_type = var.instance_type
+ key_name = var.key_name != "" ? var.key_name : null
+ vpc_security_group_ids = [aws_security_group.app_server.id]
+
+ # Cost cap: throttle to baseline when CPU credits run out instead of
+ # billing surplus credits, so compute never exceeds the hourly rate.
+ credit_specification {
+ cpu_credits = "standard"
+ }
+
+ root_block_device {
+ volume_size = var.root_volume_gb
+ volume_type = "gp3"
+ delete_on_termination = true
+ }
+
+ user_data = templatefile("${path.module}/startup.sh.tftpl", {
+ instance_name = var.instance_name
+ version = var.opencompany_version
+ app_env = var.app_env
+ })
+ user_data_replace_on_change = true
+
+ tags = {
+ Name = var.instance_name
+ }
+}
diff --git a/cli/terraform/aws/outputs.tf b/cli/terraform/aws/outputs.tf
new file mode 100644
index 00000000..13476b2a
--- /dev/null
+++ b/cli/terraform/aws/outputs.tf
@@ -0,0 +1,14 @@
+output "instance_id" {
+ description = "ID of the EC2 instance."
+ value = aws_instance.app_server.id
+}
+
+output "instance_public_ip" {
+ description = "Public IP of the EC2 instance (changes on stop/start unless an Elastic IP is attached)."
+ value = aws_instance.app_server.public_ip
+}
+
+output "url" {
+ description = "The app URL (login gate)."
+ value = "http://${aws_instance.app_server.public_ip}:${var.port}"
+}
diff --git a/cli/terraform/aws/startup.sh.tftpl b/cli/terraform/aws/startup.sh.tftpl
new file mode 100644
index 00000000..8c81a39e
--- /dev/null
+++ b/cli/terraform/aws/startup.sh.tftpl
@@ -0,0 +1,67 @@
+#!/bin/bash
+# OpenCompany EC2 startup script (cloud-init user_data, rendered by Terraform
+# `templatefile`). Runs once as root on first boot.
+#
+# Installs OpenCompany the documented way -- the repo's install.sh, run as the
+# login user, never root -- then writes the login-gate env file and runs
+# `company serve` under systemd as that user. A root install leaves the venvs
+# and ~/.opencompany owned by root (docs-internal/errors.md #16).
+#
+# NOTE on syntax: Terraform renders this file with templatefile(), so any
+# dollar-brace sequence is a Terraform interpolation. Bash variables are
+# therefore written UNBRACED ($APP_USER, $APP_HOME). `set -x` is intentionally
+# NOT used so secrets in the env file are never echoed to the console log.
+set -euo pipefail
+export DEBIAN_FRONTEND=noninteractive
+
+APP_USER=ubuntu
+APP_HOME=/home/$APP_USER
+INSTALL_SH=https://raw.githubusercontent.com/zeenie-ai/OpenCompany/main/install.sh
+
+echo "[${instance_name}] installing OpenCompany as $APP_USER..."
+sudo -u $APP_USER -H env OPENCOMPANY_VERSION="${version}" \
+ bash -c "curl -fsSL $INSTALL_SH | bash"
+
+echo "[${instance_name}] writing login-gate env..."
+mkdir -p /etc/${instance_name}
+cat > /etc/${instance_name}/opencompany.env <<'OPENCOMPANY_ENV_EOF'
+%{ for k, v in app_env ~}
+${k}=${v}
+%{ endfor ~}
+OPENCOMPANY_ENV_EOF
+chmod 600 /etc/${instance_name}/opencompany.env
+
+# DATA_DIR from app_env (default /var/lib/opencompany) must be writable by
+# the service user.
+mkdir -p /var/lib/${instance_name}
+chown $APP_USER:$APP_USER /var/lib/${instance_name}
+
+echo "[${instance_name}] installing systemd service..."
+# install.sh uses ~/.npm-global when the global prefix is not writable (the
+# apt Node case); otherwise the shim lands on the system path.
+OPENCOMPANY_BIN=$(ls $APP_HOME/.npm-global/bin/company /usr/local/bin/company /usr/bin/company 2>/dev/null | head -1)
+cat > /etc/systemd/system/${instance_name}.service <<SERVICE_EOF
+[Unit]
+Description=OpenCompany (single login-gated instance)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=$APP_USER
+WorkingDirectory=$APP_HOME
+EnvironmentFile=/etc/${instance_name}/opencompany.env
+ExecStart=$OPENCOMPANY_BIN serve
+# Lets the unprivileged service bind port 80 (inherited by the uvicorn child).
+AmbientCapabilities=CAP_NET_BIND_SERVICE
+Restart=on-failure
+RestartSec=5
+TimeoutStopSec=20
+
+[Install]
+WantedBy=multi-user.target
+SERVICE_EOF
+
+systemctl daemon-reload
+systemctl enable --now ${instance_name}
+echo "[${instance_name}] OpenCompany is ready."
diff --git a/cli/terraform/aws/terraform.tf b/cli/terraform/aws/terraform.tf
new file mode 100644
index 00000000..65c7ec2c
--- /dev/null
+++ b/cli/terraform/aws/terraform.tf
@@ -0,0 +1,10 @@
+terraform {
+ required_providers {
+ aws = {
+ source = "hashicorp/aws"
+ version = "~> 5.92"
+ }
+ }
+
+ required_version = ">= 1.2"
+}
diff --git a/cli/terraform/aws/variables.tf b/cli/terraform/aws/variables.tf
new file mode 100644
index 00000000..4ffb9c11
--- /dev/null
+++ b/cli/terraform/aws/variables.tf
@@ -0,0 +1,53 @@
+variable "region" {
+ description = "AWS region."
+ type = string
+ default = "us-east-1"
+}
+
+variable "instance_name" {
+ description = "Value of the EC2 instance's Name tag; also the systemd unit and env-file name on the VM."
+ type = string
+ default = "opencompany"
+}
+
+variable "instance_type" {
+ description = "The EC2 instance's type. t3.micro (2 vCPU, 1 GiB) is the smallest size the app runs on; 512 MB instances OOM-loop."
+ type = string
+ default = "t3.micro"
+}
+
+variable "root_volume_gb" {
+ description = "Root gp3 volume size in GiB. A fresh install uses about 4.5 GiB."
+ type = number
+ default = 10
+}
+
+variable "key_name" {
+ description = "Existing EC2 key pair name for SSH. Empty = no key pair."
+ type = string
+ default = ""
+}
+
+variable "port" {
+ description = "Public port the app binds and the security group opens."
+ type = number
+ default = 80
+}
+
+variable "allow_cidr" {
+ description = "Security group source range (e.g. 0.0.0.0/0 or <your-ip>/32)."
+ type = string
+ default = "0.0.0.0/0"
+}
+
+variable "opencompany_version" {
+ description = "opencompany version to install from npm. Empty = latest."
+ type = string
+ default = ""
+}
+
+variable "app_env" {
+ description = "KEY=VALUE map rendered into the VM's systemd EnvironmentFile. Generate with cli/commands/deploy/_secrets.py build_app_env(port=<port>)."
+ type = map(string)
+ sensitive = true
+}
diff --git a/install.sh b/install.sh
index 6679c5a8..f6e5c63d 100755
--- a/install.sh
+++ b/install.sh
@@ -314,7 +314,9 @@ main() {
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> "$HOME/.bashrc"
fi
fi
- npm install -g '@zeenie-ai/opencompany' || error_exit "npm install -g failed."
+ # OPENCOMPANY_VERSION pins a release (used by cli/terraform startup scripts).
+ PKG="@zeenie-ai/opencompany${OPENCOMPANY_VERSION:+@$OPENCOMPANY_VERSION}"
+ npm install -g "$PKG" || error_exit "npm install -g $PKG failed."
echo ""
echo -e "${GREEN}============================================${NC}"