> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macstadium.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Android emulators with the Orka CLI

> Orka CLI reference for Android emulators and emulator configurations: deploy, list, and delete emulators paired with macOS VMs on Apple silicon nodes.

> [!NOTE]
>
> Android emulators are generally available as of Orka 4.0, on Apple silicon nodes only. They were introduced as early access in Orka 3.7.0-alpha. For a conceptual overview, connection steps, and known limitations, see [Android emulators on Orka](https://docs.macstadium.com/orka/orka-resources/android-emulators.md).

## Understanding Orka emulators

An Orka emulator is an Android emulator (AVD) that runs on the same physical host node as a macOS VM, reachable from inside that VM over an ADB relay bridge. Emulators are Apple silicon only: Apple silicon does not support nested virtualization, so the emulator runs as a host-level process rather than inside the VM.

An emulator's lifecycle is tied to its paired VM. Deleting the VM automatically cleans up its emulators. In Orka 4.0, if the paired VM stops or fails, the emulator fails with the reason `PairedVMStopped` and its ports are released. You can also delete an emulator manually before deleting the VM.

If `--namespace` is not set, emulator commands use your default namespace: `ORKA_DEFAULT_NAMESPACE` if it's set, then the namespace of the `orka` context, then `orka-default`. See [Which namespace a command uses](https://docs.macstadium.com/orka/orka-cli-reference/namespace-management.md#which-namespace-a-command-uses). The aliases for `orka emulator` are `emu`, `emus`, and `emulators`.

## Emulator commands

### orka emulator deploy

Deploy an Android emulator paired with a running Orka VM. The emulator runs on the same host as the VM you specify with `--vm`.

Describe the emulator either with `--platform` and `--image-type`, or with `--config`, which takes those settings from an [emulator configuration](#emulator-configuration-commands). Any of `--platform`, `--image-type`, and `--device-profile` that you set alongside `--config` takes precedence over the configuration.

Platform, device profile, and image type values pass straight through to the Android SDK's `avdmanager` and `sdkmanager` tooling, so any combination those tools support works on a best-effort basis. The only hard constraint is architecture: only platforms with an ARM-native system image are supported, since the emulator runs directly on the Apple silicon host. The platform, system image, and device profile can't be changed after the emulator is created. To change them, delete the emulator and deploy a new one.

> [!NOTE]
>
> Deploying an emulator waits until it's running, or until the timeout elapses. A timeout is not necessarily a failure: the emulator may still be `Pending` while its AVD boots. Run `orka emulator list` to check its status.

**Syntax:**

```bash theme={null}
orka emulator deploy [AVD_NAME] --vm VM_NAME (--platform PLATFORM --image-type IMAGE_TYPE | --config EMULATOR_CONFIGURATION_NAME) [flags]
```

**Options:**

```
--vm string               (Required) The name of the running Orka VM to pair with the emulator
--platform string         (Required, unless '--config' is set) The Android platform level, as the Android SDK names it, for example 'android-35', 'android-36', 'android-37.0'
--image-type string       (Required, unless '--config' is set) The system image type, for example 'google_apis'
--config string           (Optional) The name of the emulator configuration to deploy from
--device-profile string   (Optional) The AVD device profile, for example 'pixel_8'. If omitted, the profile from '--config' is used, or the avdmanager default. Set it to "" to use the avdmanager default even when the configuration sets a profile.
--grpc                    (Optional) Start the emulator's gRPC endpoint alongside ADB. If omitted, the setting from '--config' is used, or gRPC stays off. Set it to false to keep gRPC off even when the configuration turns it on.
--generate-name           (Optional) Generate a unique name starting with the provided AVD_NAME
--timeout int             (Optional) The number of minutes to wait for the deployment to complete (default 5)
-o, --output string       (Optional) Output format: json|wide
-n, --namespace string    (Optional) The namespace to deploy the emulator in (default "orka-default")
-h, --help                Display help for deploy
```

The emulator's CPU and memory come from its device profile. You can't set them at deploy time.

If you don't provide an `AVD_NAME`, Orka generates a unique name that starts with `emu-`. If you provide a name that's already in use, the emulator isn't deployed, unless you also set `--generate-name`.

Commonly used values:

* Platforms: `android-35`, `android-36`, `android-37.0`. Use the name the Android SDK uses, including a minor version where the SDK has one.
* Device profiles: `pixel_8`, `pixel_9`, `pixel_tablet`
* Image types: `google_apis`, `google_apis_playstore`, `default`

> [!WARNING]
>
> ADB doesn't work with `google_apis_playstore` images yet. The emulator deploys, but `adb` commands fail with `device unauthorized`. Use `google_apis` or `default`. See [Android emulators on Orka](https://docs.macstadium.com/orka/orka-resources/android-emulators.md#known-limitations) for details.

**Examples:**

```bash theme={null}
# Deploy an emulator paired with a running VM
orka emulator deploy --vm my-macos-vm --platform android-36 --image-type google_apis

# Deploy a named emulator
orka emulator deploy my-emulator --vm my-macos-vm --platform android-36 --image-type google_apis

# Deploy with a specific device profile
orka emulator deploy --vm my-macos-vm --platform android-35 --image-type google_apis --device-profile pixel_8

# Deploy from an emulator configuration
orka emulator deploy --vm my-macos-vm --config android-36-google-apis

# Deploy from an emulator configuration and override its device profile
orka emulator deploy --vm my-macos-vm --config android-36-google-apis --device-profile pixel_tablet

# Deploy with the gRPC endpoint enabled
orka emulator deploy --vm my-macos-vm --platform android-36 --image-type google_apis --grpc

# Deploy on a platform whose SDK name includes a minor version
orka emulator deploy --vm my-macos-vm --platform android-37.0 --image-type google_apis

# Deploy with a longer timeout
orka emulator deploy --vm my-macos-vm --platform android-36 --image-type google_apis --timeout 10
```

The output includes the emulator's relay IP and relay port (`relayIp` and `relayPort` in JSON output). Always use these values to connect over ADB rather than a hardcoded IP or port. See [Android emulators on Orka](https://docs.macstadium.com/orka/orka-resources/android-emulators.md#connecting-from-inside-the-vm) for connection steps.

#### gRPC endpoint

When you deploy with `--grpc`, the emulator also starts its gRPC endpoint, so a gRPC client can drive the emulator or stream its display. The endpoint is reachable from the paired VM at the relay IP, on the port in the `GRPC-PORT` column of `orka emulator list`. ADB uses the `RELAY-PORT` column.

Like the ADB endpoint, the gRPC endpoint speaks plaintext gRPC over HTTP/2 with no TLS and no authentication, and only VMs on the same host can reach it. To reach it from elsewhere, forward the port through the paired VM.

> [!NOTE]
>
> First deploy on a node may be slower than later ones: Android SDK components (roughly 2 to 4 GB per platform and image type pair) download at deploy time if not already cached on the host node.

### orka emulator list

Show basic or extended information about Android emulators. With no names, lists every emulator in the namespace.

**Syntax:**

```bash theme={null}
orka emulator list [AVD_NAME_1 [AVD_NAME_2 ...]] [--namespace TARGET_NAMESPACE] [--output wide|json] [flags]
```

**Options:**

```
-o, --output string      (Optional) Output format: table (default)|wide|json
-n, --namespace string   (Optional) The namespace to list emulators from (default "orka-default")
-h, --help               Display help for list
```

**Examples:**

```bash theme={null}
# List all emulators in your default namespace
orka emulator list

# List all emulators in another namespace, with extended information
orka emulator list --namespace orka-test --output wide

# Show a specific emulator as JSON
orka emulator list my-emulator --output json
```

The default table output includes the following columns: `NAME`, `VM`, `STATUS`, `RELAY-IP`, `RELAY-PORT`, `GRPC-PORT`, `NODE`, and `AGE`. `GRPC-PORT` is empty for an emulator deployed without gRPC.

Use this command to check emulator status (`Pending`, `Running`, or `Failed`) after a deploy times out.

### orka emulator delete

Delete one or more Android emulators and free their resources on the node.

> [!WARNING]
>
> This operation cannot be undone.

> [!NOTE]
>
> Manual delete is only needed to remove an emulator before its paired VM is deleted. Deleting the VM cleans up its emulators automatically.

**Syntax:**

```bash theme={null}
orka emulator delete AVD_NAME [AVD_NAME_2 ...] [--namespace CURRENT_EMULATOR_NAMESPACE] [flags]
```

**Options:**

```
-n, --namespace string   (Optional) The namespace of the emulators (default "orka-default")
-h, --help               Display help for delete
```

**Examples:**

```bash theme={null}
# Delete an emulator from your default namespace
orka emulator delete my-emulator

# Delete two emulators from the 'orka-test' namespace
orka emulator delete my-emulator my-other-emulator --namespace orka-test
```

## Emulator configuration commands

> [!NOTE]
>
> Requires Orka 4.0 or later.

An emulator configuration is a template for deploying Android emulators. It stores the platform, system image type, and optionally a device profile and gRPC setting, so you can deploy with `--config` instead of repeating the same flags in every pipeline.

All emulator configurations reside in the `orka-default` namespace and are available to every user and service account with access to `orka-default`. Orka copies the configuration's settings into the emulator when it's deployed, so changing or deleting a configuration never affects emulators that are already running.

The alias for `orka emulator-config` is `orka emc`.

### orka emulator-config create

Create an emulator configuration. The platform and system image type are required.

The configuration name must:

* Not exceed 63 characters
* Consist of lowercase alphanumeric characters, dashes (-), or dots (.)
* Start and end with a lowercase alphanumeric character
* Be unique in the cluster

**Syntax:**

```bash theme={null}
orka emulator-config create EMULATOR_CONFIGURATION_NAME --platform PLATFORM --image-type IMAGE_TYPE [flags]
```

**Options:**

```
--platform string         (Required) The Android platform level, as the Android SDK names it, for example 'android-35', 'android-36', 'android-37.0'
--image-type string       (Required) The system image type, for example 'google_apis'
--device-profile string   (Optional) The AVD device profile, for example 'pixel_8'. If omitted, the avdmanager default is used.
--grpc                    (Optional) Start the gRPC endpoint for emulators deployed from this configuration. A deploy can turn it off with '--grpc=false'.
-h, --help                Display help for create
```

**Examples:**

```bash theme={null}
# Create a configuration for Android 36 with the 'google_apis' system image
orka emc create android-36-google-apis --platform android-36 --image-type google_apis

# Create a configuration that also sets the device profile
orka emc create pixel-8 --platform android-35 --image-type google_apis --device-profile pixel_8

# Create a configuration for a platform whose SDK name includes a minor version
orka emc create android-37-google-apis --platform android-37.0 --image-type google_apis

# Create a configuration whose emulators start the gRPC endpoint
orka emc create android-36-grpc --platform android-36 --image-type google_apis --grpc
```

### orka emulator-config list

Show basic or extended information about emulator configurations. With no names, lists every configuration.

**Syntax:**

```bash theme={null}
orka emulator-config list [EMULATOR_CONFIGURATION_1 [EMULATOR_CONFIGURATION_2 ...]] [--output wide|json] [flags]
```

**Options:**

```
-o, --output string   (Optional) Output format: table (default)|wide|json
-h, --help            Display help for list
```

**Examples:**

```bash theme={null}
# List all emulator configurations
orka emc list

# List all emulator configurations with extended information
orka emc list --output wide

# Show two specific configurations
orka emc list android-36-google-apis pixel-8
```

The default table output includes the following columns: `NAME`, `PLATFORM`, `IMAGE-TYPE`, `DEVICE-PROFILE`, `GRPC`, and `AGE`.

### orka emulator-config delete

Delete one or more emulator configurations. You can delete only the configurations you created. Orka administrators can delete any configuration. Emulators already deployed from a configuration aren't affected.

**Syntax:**

```bash theme={null}
orka emulator-config delete EMULATOR_CONFIGURATION_NAME [EMULATOR_CONFIGURATION_NAME_2 ...] [flags]
```

**Options:**

```
-h, --help   Display help for delete
```

**Examples:**

```bash theme={null}
# Delete an emulator configuration
orka emc delete android-36-google-apis

# Delete two emulator configurations
orka emc delete android-36-google-apis pixel-8
```

## Known limitations

Node-level network isolation, NAT-only networking, and other current limitations are covered in [Android emulators on Orka](https://docs.macstadium.com/orka/orka-resources/android-emulators.md#known-limitations).


## Related topics

- [Android emulators on Orka](https://docs.macstadium.com/orka/orka-resources/android-emulators.md)
- [Orka CLI Overview & Configuration](https://docs.macstadium.com/orka/orka-cli-reference/orka-cli-overview-configuration.md)
- [Manage macOS VM images with the Orka CLI](https://docs.macstadium.com/orka/orka-cli-reference/image-management.md)
- [Orka CLI command quick reference](https://docs.macstadium.com/orka/orka-cli-reference/command-quick-reference.md)
- [Android virtual devices](https://docs.macstadium.com/remote-desktop-vdi/configuration/android-virtual-devices.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.