# Install And Launch

ZoneGaze Flow can run as a direct app on Mac and Android, or through the CLI for package users and contributors.

## Mac App

The Mac app is the normal desktop path. It starts or attaches to the local runtime and opens the Matrix dashboard directly.

![Mac Matrix dashboard](./assets/screenshots/mac-desktop-dashboard-current.png)

[Watch the Mac Matrix launch clip](./assets/videos/mac-matrix-dashboard-launch.webm)

<video controls src="./assets/videos/mac-matrix-dashboard-launch.webm" title="Mac Matrix dashboard launch"></video>

Typical Mac flow:

1. Install and open ZoneGaze Flow.
2. The app starts or attaches to the runtime and opens the dashboard.
3. If the recovery screen appears, restart the runtime from there or from the tray.
4. Add or select a project.
5. Configure an agent if prompted.

## Android App

The Android app provides a native setup dashboard and uses the owned Zone Terminal backend for local runtime setup.

![Android home dashboard showing the next setup action](./assets/screenshots/android-home-dashboard.png)

Typical Android flow:

1. Install the ZoneGaze Matrix APK.
2. Open the app and keep it in view while the owned Zone Terminal runtime sets itself up.
3. Watch setup progress on Dashboard or Runtime.
4. Install the plugins you need from Plugin.
5. Open the ZoneGaze Flow WebView after the selected runtime is ready.

Current fresh Android media shows the native Dashboard, Runtime, Ports, and first embedded WebView
open states from the current emulator run.

[Watch the live Android shell navigation clip](./assets/videos/android-matrix-live-shell-navigation.mp4)

<video controls src="./assets/videos/android-matrix-live-shell-navigation.mp4" title="Android Matrix shell navigation"></video>

![Android runtime dashboard](./assets/screenshots/android-setup-dashboard.png)

![Android WebView board first open](./assets/screenshots/android-webview-board.png)

## CLI

The CLI path is useful for package users, contributors, and automation.

```bash
npx zonegaze-flow
```

or:

```bash
npm install -g zonegaze-flow
zonegaze-flow
```

After CLI launch, open the local URL shown by the command.

## Requirements

- Node.js 22 or newer for the CLI/runtime path.
- Git for worktree, branch, diff, and review features.
- At least one supported coding agent installed or configured.
- For Android, the ZoneGaze Matrix APK with owned Zone Terminal setup completed.

## After Install

Continue with [Getting started](./getting-started.md).
