> For the complete documentation index, see [llms.txt](https://docs.rumi.systems/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rumi.systems/rumi-cli/commands/cloud/aws/launch-instance.md). # launch-instance Provision and launch a Rumi service instance into an existing Rumi network. The instance is attached to the network's service-worker security group and registered in the network's Route 53 hosted zone. Optionally, a bastion can be configured to reverse-proxy external traffic into the new instance via nginx. ## Syntax ```bash rumi cloud aws launch-instance \ --profile \ --network \ --key-pair \ --type \ --name \ [options] ``` ## Options | Option | Short | Description | Default | | ------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | `--profile` | `-p` | AWS profile to use | Required | | `--region` | `-r` | AWS region | `us-east-1` | | `--network` | `-n` | Name of the Rumi network to launch the instance into | Required | | `--key-pair` | `-k` | The network's EC2 key pair | Required | | `--type` | `-t` | EC2 instance type (e.g. `t3.medium`, `m5.large`) | Required | | `--allow-internet-egress` | `-e` | Whether the instance may reach the internet; assigns a public IP in the public-subnet topology | `false` | | `--ami-id` | `-A` | The AMI ID to launch from | `null` (latest Rumi service-worker AMI) | | `--zone` | `-z` | Hosted zone to register the instance's DNS entry under | `rumi.local` | | `--name` | `-a` | Short name of the instance | Required | | `--nameInZone` | `-b` | DNS name for the instance within the hosted zone | `--name` with `-` replaced by `.` | | `--additionalNamesInZone` | `-l` | Comma-separated additional DNS names to register in the hosted zone, all pointing at this instance | `null` (none) | | `--vsize` | `-v` | Size, in GiB, of the additional (non-boot) volume on the instance | `32` | | `--service-port` | `-s` | Port the service listens on on the instance (enables bastion nginx reverse proxy) | `0` (no proxy) | | `--proxy-server` | `-x` | The nginx `server_name` to match on the bastion | `_` (matches any host) | | `--proxy-port` | `-w` | The port the bastion's nginx listens on for this service | Same as `--service-port` | | `--proxy-bastion` | `-P` | The name of the bastion that fronts this service's proxy (opens the port and registers nginx there); required for a proxying instance in a multi-bastion network, omitted in a single-bastion network | none | | `--additionalProxies` | `-q` | Per-additional-name proxy specs aligned with `--additionalNamesInZone`, comma-separated. Each entry is `servicePort[/proxyServer[/proxyPort]]` or empty for no proxy. e.g. `8080,,8443/example.com/443` | `null` (no additional-name proxies) | | `--root-volume` | `-R` | Size, in GiB, of the boot/root volume; must be > 8 when set | `0` (historical 8/32 GiB sizing) | | `--first-boot-command` | `-F` | A command or script run once at instance first boot via EC2 user-data; a bare command is wrapped in a bash shebang | `null` (no first-boot command) | | `--instance-profile` | `-I` | The IAM instance profile (name or ARN) to attach to the instance | `null` (no instance profile) | | `--elastic-ip` | `-E` | Give the instance a stable Elastic IP (survives stop/start and replacement; reused on re-launch, released at deprovision) | `false` | | `--subnet-id` | `-S` | Explicitly place the instance in this subnet, overriding the automatic topology-driven placement; the subnet must belong to the network | none (placement is automatic) | | `--tag` | `-T` | A tag (`key=value`) to apply to the instance and its volumes; repeatable | none | ## Example ```bash # Primary name proxied on 80 -> 8080, plus two additional DNS names with their own proxies rumi cloud aws launch-instance \ --profile my-aws-profile \ --network my-network \ --key-pair my-keypair \ --type t3.medium \ --name myapp \ --additionalNamesInZone api,admin,metrics \ --service-port 8080 --proxy-port 80 \ --additionalProxies 9000/_/443,,8443/internal.example.com/8443 ``` In this example: `myapp.rumi.local` serves on 80→8080, `api.rumi.local` on 443→9000, `admin.rumi.local` gets DNS only (no proxy), and `metrics.rumi.local` on 8443→8443 with `server_name internal.example.com`. ## Notes * Placement is topology-driven. In the `public-private-nat` topology, bastions land in the public subnet and everything else lands in the private subnet (reaching the internet via NAT egress, with no public IP). Pass `--subnet-id` to override automatic placement. * When `--service-port` is set, the instance's public proxy port(s) are recorded against its bastion but not opened. Open them later for specific source CIDRs with the [whitelist](/rumi-cli/commands/cloud/aws/whitelist.md) command. ## See Also * [list-instances](/rumi-cli/commands/cloud/aws/list-instances.md) * [start-instance](/rumi-cli/commands/cloud/aws/start-instance.md) * [stop-instance](/rumi-cli/commands/cloud/aws/stop-instance.md) * [terminate-instance](/rumi-cli/commands/cloud/aws/terminate-instance.md) * [resize-instance](/rumi-cli/commands/cloud/aws/resize-instance.md) * [whitelist](/rumi-cli/commands/cloud/aws/whitelist.md)