<!-- Source: https://console.uubright.com/docs/aws-host/ -->
# 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:

```json
{
  "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

```sh
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:

```sh
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](https://console.uubright.com/docs/remote-access/). No application/runner port is exposed
publicly by this module; the service listens on loopback.

## Stop, restart and remove

```sh
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:

```sh
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:**

```sh
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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html).
You can add other OpenSSH key types to `authorized_keys` after setup.
