EGO_BROWSER_AGENT_WORKSPACE Environment Variable in ego-lite: Purpose and Usage Guide

The EGO_BROWSER_AGENT_WORKSPACE environment variable overrides the default directory path where ego-lite loads agent skill files, with automatic fallback to bundled or development paths when unset.

The EGO_BROWSER_AGENT_WORKSPACE environment variable controls where the ego-lite browser automation runtime locates its agent workspace — the directory containing reusable skill files and site-specific learnings. According to the citrolabs/ego-lite source code, this variable provides flexible deployment options for containerized, multi-agent, and custom filesystem layouts.

What the EGO_BROWSER_AGENT_WORKSPACE Variable Does

In package/ego-browser/src/env.ts, the variable is defined and consumed by the workspace resolution system:

export const EGO_BROWSER_AGENT_WORKSPACE = process.env.EGO_BROWSER_AGENT_WORKSPACE || "";

This constant feeds into resolveAgentWorkspace(), which implements a three-tier fallback strategy for locating skill files.

Resolution Priority Order

The resolveAgentWorkspace() function returns the first valid path from this hierarchy:

1. EGO_BROWSER_AGENT_WORKSPACE — if explicitly set and non-empty
2. Bundled skill directory — ../skills/ego-browser relative to the compiled output
3. Development fallback — ./skills/ego-browser relative to process.cwd()

This design ensures the runtime works out-of-the-box in development while allowing production deployments to redirect skill loading to arbitrary locations.

How resolveAgentWorkspace() Implements the Logic

The resolution logic in src/env.ts demonstrates the implementation:

/**
 * Resolve the workspace directory used by the agent skills.
 * The resolution order is:
 *   1. EGO_BROWSER_AGENT_WORKSPACE env var (if set and non-empty)
 *   2. The "skill" directory bundled next to the built output
 *   3. Fallback to the repo's "skills/ego-browser" directory (used during development)
 */
export function resolveAgentWorkspace(): string {
  if (EGO_BROWSER_AGENT_WORKSPACE) {
    return EGO_BROWSER_AGENT_WORKSPACE;
  }
  // __dirname is the directory of this file after bundling (dist/out/...)
  const bundledPath = new URL("../..", import.meta.url).pathname;
  // In the bundled output, the skill dir is placed next to the output binary
  const skillPath = `${bundledPath}/skills/ego-browser`;
  if (existsSync(skillPath)) {
    return skillPath;
  }
  // Development fallback – repository layout relative to project root
  const devPath = `${process.cwd()}/skills/ego-browser`;
  return devPath;
}

Key implementation details from the source:

• Early return on environment variable — when EGO_BROWSER_AGENT_WORKSPACE has any non-empty value, it bypasses all path detection logic
• Bundled path detection — uses import.meta.url for ES module-compatible path resolution
• Synchronous existence check — existsSync() validates the bundled path before falling through

Where resolveAgentWorkspace() Gets Consumed

The workspace path propagates through the codebase via helper functions. In src/helpers.ts:

import { resolveAgentWorkspace } from "./env.js";

/** Returns the absolute path to the agent's workspace directory. */
export function getAgentWorkspace(): string {
  return resolveAgentWorkspace();
}

This abstraction allows other modules to import getAgentWorkspace() without directly depending on environment variable handling. The resolved path enables:

• Loading site-specific learnings from learnings/<site>/ subdirectories
• Validating skill configurations against the workspace schema
• Isolating multiple agents to distinct filesystem locations

Practical Usage Examples

Setting a Custom Workspace Path

Deploy ego-lite with skills mounted from a persistent volume:

export EGO_BROWSER_AGENT_WORKSPACE=/var/lib/ego-agent/workspace
ego-browser <<'JS'
  await navigate('https://example.com');
  await click('button#start');
JS

Programmatic Access in Runtime Code

Access the resolved path within agent scripts or runtime extensions:

import { resolveAgentWorkspace } from "./env.js";

const workspace = resolveAgentWorkspace();
console.log(`Loading skills from: ${workspace}`);
// Output: Loading skills from: /data/custom-workspace
// (or fallback path if EGO_BROWSER_AGENT_WORKSPACE is unset)

Loading Site-Specific Learnings

The workspace path constructs absolute paths to learning modules:

import { getAgentWorkspace } from "./helpers.js";
import { readFileSync } from "fs";

export function loadSiteLearning(site: string): object {
  const base = getAgentWorkspace();
  const learningPath = `${base}/learnings/${site}/config.json`;
  const raw = readFileSync(learningPath, "utf-8");
  return JSON.parse(raw);
}

When to Use EGO_BROWSER_AGENT_WORKSPACE

Configure this variable when you need to:

• Containerize deployments — mount skills into /app/skills or other non-standard paths
• Run multiple isolated agents — assign unique workspace directories per agent instance
• Separate skills from source code — keep skill files in a version-controlled repository distinct from the ego-lite runtime
• Enable hot-reloading in production — point to a network-mounted directory for dynamic skill updates

Without the variable set, ego-lite automatically locates skills correctly in both development (./skills/ego-browser) and standard bundled distributions.

Summary

• EGO_BROWSER_AGENT_WORKSPACE overrides the agent workspace directory path in ego-lite
• resolveAgentWorkspace() in src/env.ts implements three-tier resolution with the environment variable as highest priority
• getAgentWorkspace() in src/helpers.ts exposes the resolved path to the rest of the runtime
• The variable enables flexible deployment patterns: containers, multi-agent isolation, and custom filesystem layouts
• When unset, automatic fallback to bundled or development paths maintains out-of-the-box functionality

Frequently Asked Questions

What happens if EGO_BROWSER_AGENT_WORKSPACE points to a non-existent directory?

The runtime does not validate directory existence during resolution. System operations that attempt to read skills from the path will fail with standard filesystem errors. The calling code is responsible for ensuring the directory exists and contains valid skill files.

Can I modify EGO_BROWSER_AGENT_WORKSPACE at runtime?

The variable is read once at module initialization in src/env.ts. Changes to process.env.EGO_BROWSER_AGENT_WORKSPACE after the module loads will not affect resolveAgentWorkspace() results. Restart the process to apply new values.

How does ego-lite handle workspace paths in Windows environments?

The code uses new URL().pathname for path construction, which produces forward-slash paths compatible with Node.js cross-platform APIs. The EGO_BROWSER_AGENT_WORKSPACE value passes through unchanged, so standard Windows path formats with backslashes require manual normalization if compatibility issues arise.

Is the workspace directory the same as the Chrome profile directory?

No. The agent workspace contains skill files, learnings, and agent logic. Browser profile directories (cookies, localStorage, cache) are managed separately through Chrome DevTools Protocol configuration, not through EGO_BROWSER_AGENT_WORKSPACE.

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