# Launch an instance

Launch a virtual machine with the CLI or the API - choose an image, instance type, key pair, network and root disk - and log in over SSH.

Launch an instance to get a running Linux machine you can log in to over SSH. You choose what it boots from, its size, its key pair and where it sits on the network.

## Before you begin [#before-you-begin]

<BeforeYouBegin>

- An organization that is approved and has a valid payment method, and a project to launch into. See [Organizations](/docs/platform/organizations) and [Add a payment method](/docs/platform/billing/payment-method). The project’s URN is `urn:origin:cloud:admin::<org-id>::<project-id>`; see [Resource URNs](/docs/platform/access/api#resource-urns).
- The `origin` CLI, signed in. See [CLI access](/docs/platform/access/cli).
- A key pair in the project, and its URN from the `urn` field that `import-key-pair` or `generate-key-pair` printed. `origin compute list-key-pairs --project-urn <project-urn>` lists it again. See [Create a key pair](/docs/compute/key-pairs/create).
- Free quota for one more instance and its vCPUs, and for its root disk. See [Limits](/docs/platform/reference/limits).

</BeforeYouBegin>

## Launch the instance [#launch-the-instance]

1. Choose an instance type whose `available` is `true`:

   ```sh
   origin compute list-instance-types
   ```

   For what the fields mean, see [Instance types](/docs/compute/instances/instance-types).

1. Choose an image. List the platform-provided images and your own:

   ```sh
   origin compute list-images --project-urn <project-urn>
   ```

   To launch the current build of an image family instead, see [Using the API](#using-the-api). The CLI only launches by image URN.

1. Launch the instance:

   ```sh
   origin compute launch-instance \
     --project-urn <project-urn> \
     --image-urn <image-urn> \
     --instance-type gp1.core.2 \
     --key-pair-urn <key-pair-urn>
   ```

   With no `--subnet-urn`, the instance goes into your project’s default subnet. That subnet is created on first use, in a VPC with an internet gateway, and the instance’s network interface gets a public address automatically. See [Default VPC](/docs/network/vpcs/default-vpc).

1. Add the options you need. Each is optional:

   | Option | Use it to |
   | --- | --- |
   | `--subnet-urn <subnet-urn>` | Place the instance in a subnet of your own VPC. |
   | `--security-group-urn <security-group-urn>` | Attach security groups to the network interface. Repeat it for several groups. Omitted, the VPC’s default security group applies. You can’t change the interface’s groups after launch, only the rules inside them. See [Security groups](/docs/network/traffic-control/security-groups). |
   | `--boot-volume-size-gib <size>` | Make the root disk bigger than the image. See [Instance storage](/docs/compute/instance-storage). |
   | `--boot-volume-storage-class <class>` | Pick the root disk’s storage class. See [Storage classes](/docs/storage/volumes/storage-classes). |
   | `--login-user <name>` | Override the image’s default user. See [Guest environment](/docs/compute/instances/guest-environment). |

   `--volume-backend` accepts only `pvs`, which is the default. Leave it out.

   <Callout type="note" title="Not supported yet">

   A launch takes no user data (cloud-init configuration of your own), and instances, volumes and network resources can’t be given names or labels. Build the configuration you need into your own image, see [Create an image](/docs/compute/images/create), and keep your own record of which URN is which.

   </Callout>

1. Note the instance’s `urn` and `loginUser` in the response. The following steps use them.

1. Wait for the instance to reach `RUNNING`. Run `get-instance` until status stops changing:

   ```sh
   origin compute get-instance --instance-urn <instance-urn>
   ```

   It passes through `INITIALIZING` and `PENDING` first. If it ends up `FAILED`, read its `statusReason` and see [Status reasons](/docs/compute/reference/status-reasons). If the host never confirms the start, the instance can stay `PENDING` for about 30 minutes before it becomes `FAILED`. To poll every 10 seconds until the status stops changing, with `jq`:

   ```sh
   while :; do
     status="$(origin compute get-instance --instance-urn <instance-urn> \
       | jq -r '[.. | .status? | strings] | first')"
     echo "$status"
     case "$status" in RUNNING | STOPPED | FAILED | TERMINATED) break ;; esac
     sleep 10
   done
   ```

1. Find the instance’s public address. List the project’s floating IPs and their private addresses:

   ```sh
   origin network list-floating-ips --project-urn <project-urn>
   ```

   To match a floating IP to the instance, list the network interfaces with `origin network list-network-interfaces --project-urn <project-urn>`. The interface whose `attachedToUrn` is your instance’s URN carries its private addresses. See [Network interfaces](/docs/network/vpcs/network-interfaces).

   To print the instance’s public address in one go, with `jq`:

   ```sh
   nic="$(origin compute get-instance --instance-urn <instance-urn> \
     | jq -r '[.. | .networkInterfaceAttachments? // empty | .[].networkInterfaceUrn] | first')"
   origin network list-floating-ips --project-urn <project-urn> \
     | jq -r --arg nic "$nic" '.. | objects | select(.networkInterfaceUrn? == $nic) | .address'
   ```

1. Verify that you can log in, as the instance’s `loginUser`, with the private key of the key pair:

   ```sh
   ssh -i <private-key-file> <login-user>@<public-address>
   ```

   The VPC’s default security group allows SSH from anywhere. If you attached other security groups, one of them must allow inbound TCP port 22 from your address.

## Using the API [#using-the-api]

The `launchInstance` mutation takes the same inputs. It also accepts `imageFamily` in place of `imageUrn`, which launches the image currently designated for that family. Set exactly one of the two. See [Image families](/docs/compute/images/image-families).

```graphql
mutation {
  compute {
    launchInstance(input: {
      projectUrn: "<project-urn>"
      imageFamily: "<family-slug>"
      instanceType: "gp1.core.2"
      keyPairUrn: "<key-pair-urn>"
      bootVolume: { sizeInGib: 40 }
    }) {
      urn
      status
      loginUser
    }
  }
}
```

## If the launch is refused [#if-the-launch-is-refused]

A refused launch creates nothing and costs nothing.

- <CapacityAdvice /> The message names the type and what was short. See [`INSUFFICIENT_CAPACITY`](/docs/platform/reference/errors#insufficient_capacity).
- `PRODUCT_UNAVAILABLE`: the instance type or storage class isn’t offered. Pick one whose `available` is `true`. See [`PRODUCT_UNAVAILABLE`](/docs/platform/reference/errors#product_unavailable).
- Quota: the launch would take the organization or project past an instance, vCPU or storage limit. The error names the quota. See [Limits](/docs/platform/reference/limits).
- Root disk too small: `--boot-volume-size-gib` is smaller than the image. The error names the smallest size that works.

For other problems, see [Troubleshoot Compute](/docs/compute/troubleshooting).

## Next steps [#next-steps]

- [Attach a volume](/docs/compute/instance-storage/attach-detach)
- [Associate a floating IP](/docs/network/internet-access/floating-ips#use-a-floating-ip), for an instance in a subnet that doesn’t assign public addresses automatically
- [Stop and start an instance](/docs/compute/instances/stop-start)

## Related [#related]

- [`launch-instance` reference](/docs/compute/reference/cli#launch-instance)
- [Instance lifecycle](/docs/compute/instances/lifecycle)