How to Install the ego-lite SDK into a Browser App: Complete Setup Guide

To install the ego-lite SDK, add the ego-browser skill using npx skills add citrolabs/ego-lite, run the macOS installation script at skills/ego-browser/scripts/install.sh, and verify the integration by executing a test heredoc via ego-browser nodejs.

The ego-lite SDK delivers browser automation capabilities through the ego-browser skill in the citrolabs/ego-lite repository. This Node.js runtime communicates with the ego-lite desktop browser—a Chromium-based application—to enable automated interactions with authenticated sites without disrupting user workflows. When you install ego-lite SDK components, you gain access to helper functions like snapshotText, click, and js that execute directly within isolated browsing contexts called task spaces.

Prerequisites and System Requirements

The ego-lite SDK currently supports macOS only. You need a Node.js environment to run the npx commands, and you should have permission to install applications in ~/Applications or /Applications. The installation process modifies your PATH by adding ~/.local/bin where the ego-browser binary resides.

Step-by-Step Installation Process

1. Add the ego-browser Skill

Install the skill using the npm-style wrapper provided by the repository:

npx skills add citrolabs/ego-lite

This command clones the ego-browser skill into your local skill directory. According to skills/ego-browser/SKILL.md, this step establishes the JavaScript wrapper that injects automation helpers into heredoc scripts executed by the ego-browser command.

2. Execute the macOS Install Script

Run the bash script that downloads and registers the ego-lite desktop application:

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

As documented in skills/ego-browser/references/install.md, this script performs four critical actions: it downloads the appropriate DMG for your architecture, copies the app to ~/Applications (or /Applications), removes the macOS quarantine attribute, and launches the app for first-run onboarding.

3. Complete GUI Onboarding

The ego-lite app presents a GUI dialog asking whether to import existing Chrome data. After you respond, the app automatically adds the ego-browser binary to ~/.local/bin. Verify your PATH configuration contains this directory by running:

command -v ego-browser

If the command returns the path to the binary, the SDK is ready for command-line use.

4. Verify the SDK Installation

Confirm the installation works by executing a test heredoc:

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

If you see the output ego-browser ready, the SDK is correctly hooked into the browser runtime and ready for automation tasks.

Understanding the ego-lite SDK Architecture

When you install ego-lite SDK into your browser app workflow, you establish a three-tier architecture:

1. ego-lite app – A Chromium-based browser that runs on macOS and provides the ego-browser binary on the user’s PATH. This is the actual runtime environment.

2. ego-browser skill – A thin JavaScript wrapper defined in skills/ego-browser/SKILL.md that injects helpers into heredoc scripts. The skill executes scripts using the pattern ego-browser nodejs <<'EOF' … EOF.

3. Task spaces – Isolated browsing contexts created by helpers such as useOrCreateTaskSpace. Each space inherits the user’s Chrome data, enabling agents to operate on authenticated sites without interfering with the user’s own tabs.

Implementing Browser Automation with ego-lite SDK

Once installation is complete, you can invoke automation helpers directly from your web-app code using heredoc syntax. The following examples demonstrate common use cases.

Basic Task Space Setup and Page Snapshot

Create an isolated browsing context and capture page content:

ego-browser nodejs <<'EOF'
const task = await useOrCreateTaskSpace('demo snapshot')
await openOrReuseTab('https://example.com', { wait: true })
cliLog(await snapshotText())
EOF

This script creates a task space, navigates to the target URL, and prints a semantic snapshot of the page content.

Automating Clicks and Form Fills

Interact with DOM elements without external libraries:

ego-browser nodejs <<'EOF'
const task = await useOrCreateTaskSpace('login flow')
await openOrReuseTab('https://myapp.com/login', { wait: true })
await click('button[data-action="login"]')
await fillInput('input[name="email"]', 'user@example.com')
await fillInput('input[name="password"]', 'secret')
await click('button[type="submit"]')
cliLog('login submitted')
EOF

The click and fillInput helpers handle element detection and interaction automatically.

Uploading Files from Node Scripts

Automate file uploads using absolute paths:

ego-browser nodejs <<'EOF'
await openOrReuseTab('https://myapp.com/upload', { wait: true })
await uploadFile('input[type="file"]', '/absolute/path/to/document.pdf')
cliLog('upload finished')
EOF

The uploadFile helper targets file inputs and handles the underlying browser events.

Executing Custom JavaScript in Page Context

Extract structured data using arbitrary JavaScript:

ego-browser nodejs <<'EOF'
const data = await js(String.raw`(() => {
  const rows = [...document.querySelectorAll('table tr')]
  return rows.map(r => ({
    cells: [...r.querySelectorAll('td')].map(c => c.innerText)
  }))
})()`)
cliLog(JSON.stringify(data, null, 2))
EOF

The js helper executes self-invoking functions inside the browser context and returns serializable results.

Key Source Files and Documentation

The citrolabs/ego-lite repository contains specific files that govern the installation and operation of the SDK:

• skills/ego-browser/SKILL.md – The main skill definition that lists all available helpers (snapshotText, click, js, etc.) and usage patterns.

• skills/ego-browser/references/install.md – Detailed step-by-step installation instructions specifically for macOS environments.

• skills/ego-browser/scripts/install.sh – The bash script that automates DMG downloading, app registration, and first-run setup.

• package/ego-browser/README.md – Technical documentation explaining how the ego-browser CLI command interfaces with the desktop application.

Summary

• To install ego-lite SDK, use npx skills add citrolabs/ego-lite followed by the macOS-specific install script at skills/ego-browser/scripts/install.sh.
• The SDK operates via heredoc commands sent to ego-browser nodejs, executing JavaScript within the Chromium-based ego-lite browser.
• Task spaces provide isolated browsing contexts that inherit Chrome data, enabling automation on authenticated sites without affecting user tabs.
• Built-in helpers like useOrCreateTaskSpace, click, fillInput, and uploadFile eliminate the need for external automation libraries.
• All functionality is defined in skills/ego-browser/SKILL.md and executed through the ego-browser binary installed to ~/.local/bin.

Frequently Asked Questions

Is the ego-lite SDK available for Windows or Linux?

No, the ego-lite SDK currently supports macOS only. The installation script at skills/ego-browser/scripts/install.sh specifically handles macOS DMG files and application bundle registration. The Chromium-based ego-lite browser binary is not distributed for other operating systems in the current release.

How do I update the ego-lite SDK to a newer version?

Run the npx skills add citrolabs/ego-lite command again to pull the latest skill updates from the repository. For the desktop application itself, rerun sh skills/ego-browser/scripts/install.sh to download the most recent DMG and replace the existing ego-lite app in your Applications folder while preserving your task space configurations.

Can I use the SDK without importing my Chrome data?

Yes. During the GUI onboarding step, the application asks whether to import Chrome data. You can decline this option and the SDK will function correctly with fresh browsing contexts. However, if you need to automate tasks on authenticated sites, you will need to manually log in within the ego-lite browser or import Chrome data to preserve session cookies.

What is the difference between openOrReuseTab and creating a new task space?

useOrCreateTaskSpace creates an isolated browsing context that maintains separate cookies, localStorage, and session data, while openOrReuseTab navigates within an existing task space. Task spaces provide complete isolation between automation workflows, whereas tabs within the same task space share authentication state and browsing data.

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