# Where Are the Configuration Files for Ego-Lite Located? A Complete Guide

> Discover where ego-lite configuration files reside. This guide details locations in environment variables, TS compiler settings, package metadata, and CI/CD within the citrolabs/ego-lite repo.

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

---

**Ego-Lite stores configuration across environment variable files, TypeScript compiler settings, package metadata, learning manifests, and CI/CD workflows** — primarily in the repository root and the `package/ego-browser/` directory.

Ego-Lite's configuration system is intentionally modular, with different file types handling runtime behavior, build processes, and skill metadata. Understanding where each configuration file lives and how the [`src/env.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/env.ts) loader applies settings is essential for customizing browser agent behavior, modifying build outputs, or extending site-specific capabilities.

## Environment Variable Configuration

Ego-Lite relies on **environment variables** for all runtime configuration. These control critical paths, browser selection, and external tool integration.

### Template and Live Files

| File | Purpose |
|------|---------|
| `/.env.example` | Template showing all available variables |
| `/.env` (git-ignored) | Actual values loaded at runtime |

The `.env.example` file documents variables like `EGO_BROWSER_AGENT_WORKSPACE`, `EGO_BROWSER_NAME`, and `EGO_BROWSER_FFMPEG_PATH`. Copy this template to `.env` and customize values for your deployment.

### Runtime Loading in [`src/env.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/env.ts)

Environment variables are parsed and validated in [`package/ego-browser/src/env.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/env.ts). This module maps `process.env` entries to a typed configuration object:

```javascript
// package/ego-browser/src/env.ts excerpt
const workspace = process.env.EGO_BROWSER_AGENT_WORKSPACE || "unset";
const browserName = process.env.EGO_BROWSER_NAME || "chrome";
const ffmpegPath = process.env.EGO_BROWSER_FFMPEG_PATH;

```

If `EGO_BROWSER_AGENT_WORKSPACE` is unset, the loader falls back to `"unset"` and attempts path resolution using `HOME` (Unix) or `USERPROFILE` (Windows).

### Practical Example

```bash

# .env file in repository root

EGO_BROWSER_AGENT_WORKSPACE=/var/ego/workspaces
EGO_BROWSER_NAME=chromium
EGO_BROWSER_FFMPEG_PATH=/usr/bin/ffmpeg

```

```javascript
// Your agent code
import { env } from './src/env.js';

console.log(env.workspace);    // → /var/ego/workspaces
console.log(env.browserName);  // → chromium

```

## TypeScript Build Configuration

The **ego-browser package** compiles from TypeScript source using settings defined in [`package/ego-browser/tsconfig.json`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/tsconfig.json).

### Key Compiler Options

| Setting | Value | Effect |
|---------|-------|--------|
| `"target"` | `"es2022"` | Modern JavaScript output |
| `"module"` | `"esnext"` | ES modules for tree-shaking |
| `"outDir"` | `"./dist"` | Build artifact location |
| `"rootDir"` | `"./src"` | Source root boundary |

The `scripts/build.mjs` script consumes these settings when invoking `esbuild`:

```javascript
// package/ego-browser/scripts/build.mjs
const buildOptions = {
  target: 'es2022',
  outdir: './dist/out',
  // ... esbuild configuration aligning with tsconfig.json
};

```

## Package Metadata Configuration

[`package/ego-browser/package.json`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/package.json) defines the **entry point**, **exported helpers**, and **dependency graph** for browser agents.

Key fields include:

- `"main"`: Points to [`dist/out/index.js`](https://github.com/citrolabs/ego-lite/blob/main/dist/out/index.js) (post-build)
- `"exports"`: Declares helper context availability via `helperContext()` in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts)
- `"scripts"`: Build, test, and publishing automation

This file is consumed by npm/yarn during installation and by the learning subsystem to validate helper compatibility.

## Skill-Specific Learning Manifests

Site-aware capabilities are configured through **JSON manifests** in the skills directory.

### Manifest Location Pattern

```

skills/ego-browser/learnings/{site-name}/manifest.json

```

Each [`manifest.json`](https://github.com/citrolabs/ego-lite/blob/main/manifest.json) declares:

- Available tools for that site
- Learning notes and validation schemas
- Version constraints

The learning loader ([`src/learning/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts)) parses these at runtime:

```javascript
// Loading a learning manifest programmatically
import { loadLearning } from './src/learning/index.js';

const learning = await loadLearning('x-com');
// Reads: skills/ego-browser/learnings/x-com/manifest.json

console.log(learning.tools);  // Site-specific tool definitions

```

## CI/CD and Workflow Configuration

GitHub Actions workflows live in `.github/workflows/*.yml`. These control:

- Automated testing on pull requests
- Package publishing on version tags
- Quality gate enforcement

These YAML files are not loaded at application runtime but govern repository automation.

## Complete Configuration File Reference

| File Path | Configuration Domain | Runtime/Build |
|-----------|----------------------|---------------|
| `/.env.example` | Environment template | Documentation |
| `/.env` | Live environment values | **Runtime** |
| [`package/ego-browser/src/env.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/env.ts) | Environment loader | **Runtime** |
| [`package/ego-browser/tsconfig.json`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/tsconfig.json) | TypeScript compilation | **Build** |
| [`package/ego-browser/package.json`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/package.json) | Package metadata | **Build** + Runtime |
| `package/ego-browser/scripts/build.mjs` | Build orchestration | **Build** |
| `skills/ego-browser/learnings/**/manifest.json` | Skill definitions | **Runtime** |
| `.github/workflows/*.yml` | CI/CD automation | Neither (GitHub Actions) |

## Summary

- **Environment variables** in `.env` (copied from `.env.example`) control all runtime behavior, loaded via [`src/env.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/env.ts)
- **[`tsconfig.json`](https://github.com/citrolabs/ego-lite/blob/main/tsconfig.json)** and **[`package.json`](https://github.com/citrolabs/ego-lite/blob/main/package.json)** in `package/ego-browser/` govern TypeScript compilation and package structure
- **Learning manifests** in `skills/ego-browser/learnings/` enable site-specific agent capabilities
- **GitHub Actions workflows** automate testing and publishing without affecting runtime

Configuration changes require different deployment strategies: `.env` updates take effect immediately on restart, while [`tsconfig.json`](https://github.com/citrolabs/ego-lite/blob/main/tsconfig.json) or manifest modifications need a rebuild.

## Frequently Asked Questions

### Where do I set the workspace directory for Ego-Lite?

Set `EGO_BROWSER_AGENT_WORKSPACE` in a `.env` file at the repository root or export it in your shell environment. The [`src/env.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/env.ts) loader reads this variable; if missing, it defaults to `"unset"` and attempts fallback resolution using `HOME` or `USERPROFILE`.

### Do I need to rebuild after modifying [`tsconfig.json`](https://github.com/citrolabs/ego-lite/blob/main/tsconfig.json)?

Yes. Changes to [`package/ego-browser/tsconfig.json`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/tsconfig.json) require running the build script (`scripts/build.mjs`) to regenerate [`dist/out/index.js`](https://github.com/citrolabs/ego-lite/blob/main/dist/out/index.js) with new compiler settings. Environment variable changes do not require a rebuild.

### How do I add configuration for a new site my agent should handle?

Create a new directory under `skills/ego-browser/learnings/` with a [`manifest.json`](https://github.com/citrolabs/ego-lite/blob/main/manifest.json) describing tools and schemas for that site. The `loadLearning()` function in [`src/learning/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts) will automatically discover and parse your manifest at runtime.

### Can I use environment variables without creating a `.env` file?

Yes. [`src/env.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/env.ts) reads from `process.env` directly, so exporting variables in your shell or injecting them via container orchestration (Docker, Kubernetes) works identically to a `.env` file. The `.env` file is merely a convenience for local development.