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

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 source code, the official installation flow is macOS-only and handled by the helper script located at 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/.

Step-by-Step Ego-Lite Installation

Step 1: Run the Official Install Script

The installation is driven by skills/ego-browser/scripts/install.sh. This script is idempotent—running it multiple times simply opens the already-installed app.

# 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:

command -v ego-browser

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

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

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

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

Run the Runtime Sanity Check

Confirm Ego-Lite executes JavaScript correctly:

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:

// 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 and loaded through the harness architecture described in 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/

Key Ego-Lite Installation Files

Understanding these source files helps debug issues:

• skills/ego-browser/scripts/install.sh — The automated installer that fetches and configures Ego-Lite
• skills/ego-browser/references/install.md — Human-readable onboarding steps and troubleshooting guide
• skills/ego-browser/SKILL.md — Canonical documentation for the ego-browser skill interface
• package/ego-browser/README.md — SDK overview and usage patterns
• 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
• 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 script exits immediately on non-Darwin systems. For Linux or Windows, download the appropriate installer manually from 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}