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

> Learn the purpose and usage of the EGO_BROWSER_AGENT_WORKSPACE environment variable in ego-lite. Discover how it customizes agent skill file loading.

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

---

**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`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/env.ts), the variable is defined and consumed by the workspace resolution system:

```typescript
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`](https://github.com/citrolabs/ego-lite/blob/main/src/env.ts) demonstrates the implementation:

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

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

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

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

```typescript
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`](https://github.com/citrolabs/ego-lite/blob/main/src/env.ts) implements three-tier resolution with the environment variable as highest priority
- **`getAgentWorkspace()`** in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`.