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

> Install the ego-lite SDK into your browser app with this complete setup guide. Learn how to add the ego-browser skill and verify integration easily.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: how-to-guide
- Published: 2026-08-24

---

**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`](https://github.com/citrolabs/ego-lite/blob/main/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:

```bash
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`](https://github.com/citrolabs/ego-lite/blob/main/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:

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

```

As documented in [`skills/ego-browser/references/install.md`](https://github.com/citrolabs/ego-lite/blob/main/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:

```bash
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:

```bash
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`](https://github.com/citrolabs/ego-lite/blob/main/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:

```bash
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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/references/install.md)** – Detailed step-by-step installation instructions specifically for macOS environments.

- **[`skills/ego-browser/scripts/install.sh`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/scripts/install.sh)** – The bash script that automates DMG downloading, app registration, and first-run setup.

- **[`package/ego-browser/README.md`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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.