# unikraft instances run

Create an instance and optionally follow its logs.

```
unikraft instances run [flags]
```

## Examples

Deploy a new instance and expose a HTTPS service:

```bash
unikraft instance run --metro=sfo --image=nginx:latest -p 443:8080/http+tls
```

Deploy a new instance and expose a HTTPS service and redirect from HTTP to HTTPS:

```bash
unikraft instance run --metro=sfo --image=nginx:latest -p 443:8080/http+tls -p 80:443/http+redirect
```

Deploy and tail logs from a new instance:

```bash
unikraft instance run --metro=fra --image=nginx:latest --follow
```

Preview instance creation without executing:

```bash
unikraft instance run --metro=dal --image=nginx:latest --dry-run
```

Deploy a new instance with environment variables:

```bash
unikraft instance run --metro=was --image=my-app:latest -e KEY1=VALUE1 -e KEY2=VALUE2
```

Deploy a new instance with attached volume:

```bash
unikraft instance run --metro=sin --image=my-app:latest -v my-volume:/data
```

Deploy a new instance with attached volume which is read-only:

```bash
unikraft instance run --metro=sin --image=my-app:latest -v my-volume:/data:ro
```

Deploy a new instance with custom resource allocations:

```bash
unikraft instance run --metro=sfo --image=my-app:latest -m 512MiB --vcpus 2
```

Deploy a new instance with scale-to-zero enabled:

```bash
unikraft instance run --metro=fra --image=my-app:latest --scale-to-zero policy=on,cooldown-time=300
```

Deploy a new instance with specific restart policy:

```bash
unikraft instance run --metro=dal --image=my-app:latest --restart=on-failure
```

## Options

```
  --annotation <key>=<value>  Instance annotation.
  --args arg                  Arguments to pass to the instance.
  --autostart                 Start instance automatically.
  --branch instance           Branch from an existing instance.
  --checkpoint checkpoint     Create from a checkpoint.
  --cmd CMD                   Run a command to edit fields (receives YAML on stdin, outputs edited YAML on stdout).
  --domain fqdn               Service domain.
  --dry-run                   Print patches without applying them.
  -e, --env <key>=<value>     Environment variable.
  --feature feature           Instance feature.
  -f, --field FIELD           Specify which fields to include in the output.
  --follow                    Follow instance logs after creation.
  --gpus n                    Number of GPUs to attach. Requires type "full" and a plan with GPU support. Currently limited to 1.
  --image <name>:<tag>        Image to deploy.
  --load LOAD                 Load fields from a YAML file.
  -m, --memory size           Memory allocation.
  --metro metro               Metro to deploy in.
  -n, --name name             Instance name.
  -o, --output OUTPUT         Output format. One of: kv, table, json, yaml, raw, quiet, template.
  -p, --publish <src>:<dest>[/<handlers>]  Publish port.
  --pull-policy policy        Image pull policy.
  --replicas n                Number of replicas.
  --restart policy            Restart policy.
  --rm                        Automatically delete the instance when it stops.
  --rom image=<ref>,at=<path> Attach ROM.
  --save FILE                 Save creatable fields as YAML to a file (use - for stdout).
  --scale-to-zero <key>=<value>  Scale-to-zero options.
  policy: on | idle | off
  cooldown-time: cooldown in ms before scaling to zero
  notify-time: notification time in ms before scaling to zero
  stateful: true | false
  --sched-priority priority   Scheduling priority for the instance.
  --service name              Service group name or key.
  --set <name>=<value>        Key-value pairs to set on the instance.
  --set-file <name>=<filename>  Files containing key-value pairs to set on the instance.
  --tag tag                   Instance tag.
  --template name             Create from instance template.
  --type type                 Type of virtual machine to run. "full" requires a plan with full VM support.
  --vcpus n                   Number of vCPUs.
  --visual                    Open an editor to modify fields visually.
  -v, --volume <name>:<path>[:<options>]  Attach volume.
```

## Options inherited from parent commands

```
  --config file               Path to the configuration file.
  --log-level level           Set the logging level. (default info)
  --log-type type             Set the log type. (default text)
  --profile name              Set the current profile.
  --telemetry                 Toggle anonymous usage analytics. (default true)
  --timeout duration          Set a deadline for the command (e.g. 30s, 5m, 1h).
```

## See Also

* [`unikraft instances`](../instances.mdx): Manage Unikraft Cloud instances.