Launch an AWS coding host

Provision uuBright Console in your own AWS account with an OpenTofu-compatible Terraform configuration. AWS bills you directly. The first supported configuration is an Ubuntu 24.04 x86_64 EC2 host; it needs no hosted account, model gateway, or Cloudflare.

#Before you begin

Install AWS CLI and sign in with permission to manage EC2 instances, encrypted EBS volumes, key pairs, VPCs, subnets, routes, internet gateways and security groups. The module creates its own network and never modifies an existing VPC. It creates no IAM role and copies no AWS credentials to the host.

Install OpenTofu or Terraform. The supported test matrix is OpenTofu 1.13.1, Terraform 1.16.6 and the pinned AWS provider 6.38.0. An SSH client and your own SSH public/private key pair are also required. Keep your private key on your laptop.

Create a private host.json outside the repository:

{
  "name": "my-coding-host",
  "region": "us-east-1",
  "availability_zone": "us-east-1a",
  "ssh_cidr": "YOUR_PUBLIC_IPV4/32",
  "ssh_public_key": "ssh-ed25519 YOUR_PUBLIC_KEY",
  "instance_type": "t3.small",
  "size_gib": 20
}

Replace both placeholders. SSH is restricted to that one IPv4 address. Update it if your laptop address changes. If HTTPS and SSH use different network paths, use the actual SSH source address (the first field of $SSH_CONNECTION in an existing server SSH session). Choose an availability zone in your region. source_revision optionally pins another full commit SHA of uuBright Console; the default is the first release. These inputs contain no model or Git credentials. Never add credentials to Terraform variables or cloud-init.

#Plan and create

SHELL
npm run host -- plan --config /path/host.json
npm run host -- create --config /path/host.json --yes

Set TOFU_BIN=terraform to use Terraform instead of the default tofu executable. Choose one CLI for a deployment; do not alternate state writers casually. Each deployment generates and retains its own provider lock file with its state; the shared configuration pins the provider version.

State is stored under ~/.local/share/ccr-cloud/hosts/NAME/. Use CCR_HOST_STATE for a different private state root. Keep and back up this directory: it records resource ownership. The command refuses concurrent operations on the same host. If an operation fails, retain state and retry after inspecting the error.

The initial plan uses a placeholder attachment ID until the data disk exists. Create applies the data stack first, then plans/applies the host with its real disk. Review the costs and resource changes before creating. Provisioning usually takes several minutes; successful infrastructure creation does not imply bootstrap is finished.

#Finish setup

Use the printed SSH command, then:

SHELL
cloud-init status --wait
sudo systemctl status ccr-cloud
claude auth login
gh auth login

Claude Code and Codex are installed, but you must configure agent/model access under your own account and terms. Installation does not imply that uuBright Console supports every installed agent. GitHub login is optional for scratch tasks.

Bootstrap logs: /var/log/ccr-cloud-bootstrap.log and /var/log/cloud-init-output.log. Service logs: sudo journalctl -u ccr-cloud. A successful bootstrap creates /var/lib/ccr-cloud-ready.

On your laptop, use the printed SSH forwarding command and open http://localhost:8787. Retrieve the owner token on the host from ~/.local/share/ccr-cloud/server.env; do not paste it into issues or logs. Run a scratch task before selecting a repository. For phone access, follow Access from your phone. No application/runner port is exposed publicly by this module; the service listens on loopback.

#Stop, restart and remove

SHELL
npm run host -- status --config /path/host.json
npm run host -- stop --config /path/host.json --yes
npm run host -- start --config /path/host.json --yes
npm run host -- status --config /path/host.json

These requests are asynchronous; use status to check completion. The public IP can change after stop/start. The separately encrypted disk holds /home/ubuntu, including repositories, uncommitted work, uuBright Console data and agent login state. Running tasks may need manual Resume after a host restart; this does not promise that processes continue through a reboot. No task prompt is automatically resent by the provisioning command.

Preview compute removal, then explicitly apply it:

SHELL
npm run host -- destroy --config /path/host.json
npm run host -- destroy --config /path/host.json --yes

This removes the instance, root disk, network and SSH key-pair resource but retains the separate home/data disk. create can attach that disk to replacement compute in the same availability zone. Back up important data before any lifecycle action.

Permanent data deletion is separate and irreversible:

SHELL
npm run host -- delete-data --config /path/host.json --yes --confirm-data-loss my-coding-host

It refuses while the host stack still contains an instance. Independently created snapshots and backups are not deleted. If state is lost, inspect resource tags ccr-cloud=NAME in AWS and recover/import state before operating; never guess IDs or destroy resources solely because a name matches.

#Charges and limits

Compute, EBS storage, public IPv4, data transfer and any snapshots can incur AWS charges. Stopped compute does not eliminate storage charges; a retained disk after destroy also remains billable. The module creates no NAT gateway, load balancer, elastic IP or automatic snapshots. Check current AWS pricing for your region and instance, including CPU credit policies. The module uses standard credits for burstable T-family instances so it does not opt you into surplus CPU credit charges. There is no automatic expiry, budget enforcement or billing cap in this first version. Remove disposable test resources and separately delete their retained data when finished.

The host module requires an x86_64 Nitro instance with NVMe EBS support, such as t3.small. Older Xen types (t2, m4, c4) are rejected before provisioning. A failed preflight does not bind the deployment name to its availability zone. Existing hosts keep their original AMI when Ubuntu publishes a newer image; inspect plan before applying configuration or bootstrap changes.

The service uses the same generated start.sh and shell-parsed server.env as manual setup, including its configured port. If the data volume is missing, boot can continue for SSH recovery, but the coding service requires /home/ubuntu to be mounted and will not run against an empty replacement home directory.

For initial SSH access, supply an RSA or Ed25519 public key: these are the types EC2 key-pair import supports. You can add other OpenSSH key types to authorized_keys after setup.