# How to Install Ego-Lite on macOS: Complete Setup Guide

> Easily install Ego-Lite on macOS with our complete setup guide. Run a single bash script to download, install, and register the ego-browser command. Get started now.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: getting-started
- Published: 2026-08-03

---

**Ego-Lite is installed by running a single bash script that downloads the DMG, installs it to your Applications folder, and registers the `ego-browser` command to `~/.local/bin`.**

Ego-Lite is a lightweight browser runtime that powers the **ego-browser** skill in agent workflows. According to the [citrolabs/ego-lite](https://github.com/citrolabs/ego-lite) source code, the official installation flow is macOS-only and handled by the helper script located at [`skills/ego-browser/scripts/install.sh`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/scripts/install.sh). This guide walks you through verifying your installation, completing the onboarding wizard, and running a quick sanity check to confirm everything works.

## Prerequisites for Installing Ego-Lite

Before running the install script, ensure your system meets these requirements:

- **macOS only** — the installer checks `uname -s` for `Darwin` and exits on other platforms
- Network access to download the DMG from the official CDN
- Terminal access to run shell commands

If you're on Linux or Windows, you must download the installer manually from [https://lite.ego.app/](https://lite.ego.app/).

## Step-by-Step Ego-Lite Installation

### Step 1: Run the Official Install Script

The installation is driven by [`skills/ego-browser/scripts/install.sh`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/scripts/install.sh). This script is idempotent—running it multiple times simply opens the already-installed app.

```bash

# From the repository root or any location

sh skills/ego-browser/scripts/install.sh

```

The script performs four operations automatically:

1. Detects your CPU architecture (ARM64 or x86-64)
2. Downloads the matching Ego-Lite DMG
3. Installs to `/Applications` (or `~/Applications` for user installs)
4. Strips the quarantine attribute and launches the app

### Step 2: Complete the GUI Onboarding Wizard

When the Ego-Lite app opens, follow the on-screen wizard:

- **Import data** (optional): Bring bookmarks and settings from Chrome or another browser
- **Allow PATH registration**: The wizard registers the `ego-browser` command in `~/.local/bin`

This step is critical—the `ego-browser` CLI becomes available only after onboarding completes.

## Verify Your Ego-Lite Installation

### Check the Command Is on PATH

Open a new terminal and run:

```bash
command -v ego-browser

```

If the command returns nothing, temporarily prepend the installation directory:

```bash
export PATH="$HOME/.local/bin:$PATH"
command -v ego-browser

```

For permanent access, add `~/.local/bin` to your shell profile (`.zshrc` or `.bash_profile`):

```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

```

### Run the Runtime Sanity Check

Confirm Ego-Lite executes JavaScript correctly:

```bash
ego-browser nodejs <<'EOF'
console.log('ego-browser ready')
EOF

```

You should see `ego-browser ready` printed to stdout. This verifies the runtime is fully operational.

## Using Ego-Browser in Agent Scripts

Once installed, the `ego-browser` command integrates with agent workflows. The runtime automatically injects helper objects like `nav` and `observe` into your execution context:

```javascript
// Example: navigate and capture a screenshot
await nav.goto('https://example.com');
await observe.screenshot({ path: 'example.png' });

```

These helpers are provided by the ego-browser skill as defined in [`skills/ego-browser/SKILL.md`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/SKILL.md) and loaded through the harness architecture described in [`AGENTS.md`](https://github.com/citrolabs/ego-lite/blob/main/AGENTS.md).

## Troubleshooting Common Issues

| Issue | Cause | Solution |
|-------|-------|----------|
| `ego-browser: command not found` | PATH not updated or onboarding incomplete | Re-run onboarding or manually add `~/.local/bin` to PATH |
| Gatekeeper blocks launch | macOS security quarantine | The install script removes the quarantine attribute; if blocked, allow via System Settings → Privacy & Security |
| Download fails | Network or CDN issue | Retry the install script after verifying connectivity |
| Non-macOS platform | Installer limitation | Download manually from [https://lite.ego.app/](https://lite.ego.app/) |

## Key Ego-Lite Installation Files

Understanding these source files helps debug issues:

- **[`skills/ego-browser/scripts/install.sh`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/scripts/install.sh)** — The automated installer that fetches and configures Ego-Lite
- **[`skills/ego-browser/references/install.md`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/references/install.md)** — Human-readable onboarding steps and troubleshooting guide
- **[`skills/ego-browser/SKILL.md`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/SKILL.md)** — Canonical documentation for the ego-browser skill interface
- **[`package/ego-browser/README.md`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/README.md)** — SDK overview and usage patterns
- **[`AGENTS.md`](https://github.com/citrolabs/ego-lite/blob/main/AGENTS.md)** — Architecture of how the skill loads into agent runtimes

## Summary

- **Ego-Lite installation requires macOS** and is handled by [`skills/ego-browser/scripts/install.sh`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/scripts/install.sh)
- The script downloads the correct DMG, installs the app, and removes quarantine attributes automatically
- **Onboarding registers the `ego-browser` command** to `~/.local/bin`—this step cannot be skipped
- Verify installation with `command -v ego-browser` and the heredoc sanity check
- The install script is **idempotent**—safe to re-run if you need to reopen the app

## Frequently Asked Questions

### How do I install ego-lite on Linux or Windows?

The official [`install.sh`](https://github.com/citrolabs/ego-lite/blob/main/install.sh) script exits immediately on non-Darwin systems. For Linux or Windows, download the appropriate installer manually from [https://lite.ego.app/](https://lite.ego.app/) and follow the platform-specific instructions there.

### Why is `ego-browser` not found after installation?

The command is registered during the GUI onboarding wizard, not by the install script itself. If you skipped onboarding, relaunch Ego-Lite from Applications and complete the wizard. Also verify `~/.local/bin` is in your PATH.

### Can I automate ego-lite installation without the GUI?

No—according to the source code in [`skills/ego-browser/references/install.md`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/references/install.md), the PATH registration requires user interaction through the onboarding wizard. The GUI step is mandatory for CLI availability.

### Is the install script safe to run multiple times?

Yes. The script checks for existing installations and simply opens the app if Ego-Lite is already present. It will not re-download or duplicate the installation.