# How the EGO_BROWSER_AGENT_WORKSPACE Environment Variable Is Resolved in citrolabs/ego-lite

> Discover how citrolabs/ego-lite resolves the EGO_BROWSER_AGENT_WORKSPACE env variable through a three-step hierarchy: user overrides, skill directories, and default repository locations.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: internals
- Published: 2026-07-28

---

**The `EGO_BROWSER_AGENT_WORKSPACE` environment variable is resolved through a three-step hierarchy in [`package/ego-browser/src/env.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/env.ts), checking explicit user overrides, bundled skill directories, and finally defaulting to the repository's `skills/ego-browser` folder.**

The `EGO_BROWSER_AGENT_WORKSPACE` environment variable determines the file system location where the Ego browser agent stores and retrieves skill files. In the citrolabs/ego-lite repository, resolution logic is centralized in the `agentWorkspace()` helper function within [`package/ego-browser/src/env.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/env.ts). This implementation provides a robust fallback chain that ensures the runtime always locates a valid workspace directory.

## Three-Tier Resolution Hierarchy

The `agentWorkspace()` function implements a deterministic resolution strategy that prioritizes user configuration over system defaults.

### Explicit Environment Variable Override

When `EGO_BROWSER_AGENT_WORKSPACE` is present in the environment, its value takes precedence. According to lines 9-11 in [`package/ego-browser/src/env.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/env.ts), the function passes the variable's value through `resolvePath()` to convert it to an absolute path. This allows users to specify custom workspace locations anywhere on the file system.

### Bundled Skill Fallback

If the environment variable is unset, the code checks for a bundled copy of the `ego-browser` skill adjacent to the compiled sources. As implemented in lines 13-16, the function verifies whether `SRC_DIR/ego-browser` exists and returns its absolute path if found. This supports packaged distributions where skills ship alongside the compiled JavaScript.

### Repository Default

When neither custom overrides nor bundled skills are available, the function falls back to the repository's default location. Lines 18-19 define this as `skills/ego-browser`, resolved relative to the source root two directory levels up from the current file. This default ensures the development environment works immediately after cloning without additional configuration.

## Path Normalization with resolvePath()

The `resolvePath()` helper (lines 21-25) performs essential path transformations before returning the final absolute path. Most notably, it expands a leading tilde (`~`) to the current user's home directory. This means setting `EGO_BROWSER_AGENT_WORKSPACE=~/custom-skills` correctly resolves to `/home/username/custom-skills` (or equivalent) before path validation occurs.

## Practical Usage Examples

The following JavaScript examples demonstrate the three resolution paths in practice:

```javascript
// Default resolution (no env var set)
console.log(agentWorkspace());
// → /path/to/repo/skills/ego-browser

// Explicit absolute path override
process.env.EGO_BROWSER_AGENT_WORKSPACE = "/custom/skill/path";
console.log(agentWorkspace());
// → /custom/skill/path

// Home directory shortcut expansion
process.env.EGO_BROWSER_AGENT_WORKSPACE = "~/my-skill";
console.log(agentWorkspace());
// → /home/youruser/my-skill

```

## Integration with the Learning Subsystem

The resolved workspace path is consumed throughout the browser agent, particularly by the learning subsystem defined in [`src/learning/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts) (lines 201-205). After calling `agentWorkspace()`, the learning module uses the returned path to locate skill files for training and inference operations, logging the resolved location during initialization to aid debugging.

## Summary

- **Explicit override takes precedence**: Setting `EGO_BROWSER_AGENT_WORKSPACE` forces the runtime to use your specified path via `resolvePath()` in [`package/ego-browser/src/env.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/env.ts).
- **Tilde expansion supported**: Paths starting with `~` automatically expand to the user's home directory before resolution completes.
- **Three-tier fallback**: The system checks environment variables, then bundled skills (`SRC_DIR/ego-browser`), then defaults to the repository's `skills/ego-browser` directory.
- **Learning subsystem dependency**: Components like the learning system in [`src/learning/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts) rely on this resolution to locate skill assets at runtime.

## Frequently Asked Questions

### What happens if EGO_BROWSER_AGENT_WORKSPACE is not set?

When the environment variable is absent, the `agentWorkspace()` function proceeds to check for a bundled skill directory at `SRC_DIR/ego-browser`. If that directory does not exist, it falls back to the repository default at `skills/ego-browser`, located two levels up from the source root in [`package/ego-browser/src/env.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/env.ts).

### Can I use a tilde (~) in the workspace path?

Yes. The `resolvePath()` helper in [`package/ego-browser/src/env.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/env.ts) (lines 21-25) automatically expands leading tildes to the current user's home directory. This allows portable configurations like `EGO_BROWSER_AGENT_WORKSPACE=~/ego-skills` to work correctly across different user accounts.

### Which source file contains the resolution logic?

The resolution logic is implemented in [`package/ego-browser/src/env.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/env.ts) within the `agentWorkspace()` function (lines 9-19), with path normalization handled by `resolvePath()` (lines 21-25) in the same file.

### How does the learning subsystem use this path?

The learning subsystem in [`src/learning/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts) (lines 201-205) calls `agentWorkspace()` during initialization to determine where skill files are stored. It logs the resolved path and uses it to locate training data and skill configurations required for browser automation tasks.