# IEUM

IEUM is an open-source coding agent you can use in three places:

- terminal (`TUI`)
- browser (`WEB`)
- VS Code (`Extension`)

It shares one agent core across all three, so your workflow stays consistent.

---

## At A Glance

| Platform | Recommended Use | Runtime |
|---|---|---|
| TUI | Local development on your machine | Local |
| WEB | Centralized team server | Remote |
| VS Code | Both local and remote workflows | Local / Remote |

---

## What You Get

- One agent core across TUI, WEB, and VS Code
- Tool use with approval flow (HITL)
- Session history and resume support
- Multi-provider LLM support (OpenAI, Anthropic, Ollama, OpenRouter, and more)
- Skill system (built-in + user/project skills)
- MCP integration (including GitHub MCP)
- English and Korean UI

---

## Quick Start

### 1) Install

```bash
pip install ieum
```

Or with `uv`:

```bash
uv pip install ieum
```

### 2) Run TUI (local)

```bash
ieum
```

### 3) Run WEB

```bash
ieum --web --host 127.0.0.1 --port 8765
```

Open `http://127.0.0.1:8765` and log in with the token printed in the server console.

---

## Installation

### Prerequisites

- Python 3.11+
- `ripgrep` recommended for fast code search

### From Source

```bash
git clone https://github.com/ieum/ieum.git
cd ieum
pip install -e .
```

Install WEB dependencies:

```bash
pip install -e ".[server]"
```

Install test/dev dependencies:

```bash
uv sync --group test
```

---

## Configuration

### Core Environment Variables

| Variable | Default | Purpose |
|---|---|---|
| `IEUM_LANG` | `en` | UI language (`en` / `ko`) |
| `IEUM_AUTH_DISABLED` | `false` | Disable auth (local dev only) |
| `IEUM_AUTH_TOKEN_TTL_SECONDS` | `3600` | Auth token TTL (min 60s) |
| `IEUM_CORS_ORIGINS` | localhost-only list | Allowed browser origins |
| `IEUM_REMOTE_ONLY` | `false` | Block loopback-only bind in remote deployments |
| `IEUM_TLS_REQUIRED` | `false` | Require HTTPS/WSS |
| `IEUM_TRUST_PROXY_TLS` | `false` | Trust `X-Forwarded-Proto=https` from proxy |
| `IEUM_SSL_CERTFILE` | unset | TLS cert path (direct TLS termination) |
| `IEUM_SSL_KEYFILE` | unset | TLS key path (direct TLS termination) |
| `IEUM_RATE_LIMIT_ENABLED` | `true` | Enable per-IP rate limiting |
| `IEUM_RATE_LIMIT_MAX_REQUESTS` | `120` | Max requests per window |
| `IEUM_RATE_LIMIT_WINDOW_SECONDS` | `60` | Rate limit window |
| `IEUM_SANDBOX_ROOT` | unset | Root for `<user>/<workspace>` sandboxing |
| `IEUM_REQUIRE_USER_ID` | `false` | Require user identity header/query |
| `IEUM_SAFE_MODE` | `false` | Extra command restrictions |

### LLM Variables (Common)

| Provider | Variables |
|---|---|
| OpenAI | `OPENAI_API_KEY`, `OPENAI_MODEL` |
| Anthropic | `ANTHROPIC_API_KEY`, `ANTHROPIC_MODEL` |
| Ollama | `OLLAMA_BASE_URL`, `OLLAMA_MODEL` |
| OpenRouter | `OPENROUTER_API_KEY`, `OPENROUTER_MODEL` |
| Google | `GOOGLE_API_KEY` |

### `.env` Priority

1. Project `.env` (current directory)
2. User `.env` (`~/.ieum/.env`)
3. System environment

### Config Directory

```text
~/.ieum/
  .env
  auth_token
  <agent>/
    AGENTS.md
    skills/
```

---

## Usage

### TUI (Local)

```bash
# interactive
ieum

# use a specific model
ieum --model anthropic/claude-sonnet-4-5-20250929

# resume latest thread
ieum -r

# auto-approve tool calls
ieum --auto-approve
```

Useful commands in chat:

- `/help`
- `/env`
- `/model <provider/model>`
- `/skills`
- `/threads`
- `/tokens`

### WEB (Remote-first)

Local check:

```bash
ieum --web --host 127.0.0.1 --port 8765
```

Remote deployment baseline:

```bash
export IEUM_REMOTE_ONLY=true
export IEUM_TLS_REQUIRED=true
export IEUM_TRUST_PROXY_TLS=true
export IEUM_CORS_ORIGINS="https://ieum.example.com"
export IEUM_AUTH_TOKEN_TTL_SECONDS=3600
export IEUM_RATE_LIMIT_ENABLED=true
export IEUM_RATE_LIMIT_MAX_REQUESTS=120
export IEUM_RATE_LIMIT_WINDOW_SECONDS=60
export IEUM_SANDBOX_ROOT="/srv/ieum/sandboxes"
export IEUM_REQUIRE_USER_ID=true

ieum --web --host 0.0.0.0 --port 8765
```

Notes:

- Wildcard CORS (`*`) is rejected.
- In required-user mode, send one of:
  - header `x-ieum-user-id`
  - header `x-ieum-user`
  - query `user_id`

### VS Code Extension

VS Code supports local, remote, and auto modes.

Key settings:

- `ieum.serverMode`: `local` | `remote` | `auto`
- `ieum.remoteServerUrl`
- `ieum.authToken`
- `ieum.serverPort`
- `ieum.pythonPath`

See `docs/VSCODE_MODE.md` for setup and troubleshooting.

---

## Production Checklist (WEB)

Before exposing the server:

1. Set explicit `IEUM_CORS_ORIGINS` (no `*`)
2. Enable `IEUM_TLS_REQUIRED=true`
3. Set token TTL (`IEUM_AUTH_TOKEN_TTL_SECONDS`)
4. Keep rate limit enabled
5. Set `IEUM_SANDBOX_ROOT`
6. Enable `IEUM_REQUIRE_USER_ID=true` for multi-user use

---

## Architecture

```text
TUI (Textual)     WEB (FastAPI/WS)     VS Code (Extension/WebView)
         \             |                        /
          \            |                       /
                 LangGraph Agent Core
                       |
            Tools (file/shell/search/MCP/skills)
```

Main code locations:

| Area | Path |
|---|---|
| Agent core | `ieum/agent.py` |
| TUI app | `ieum/app.py` |
| WEB server | `ieum/server/` |
| Sessions/persistence | `ieum/sessions.py` |
| Skills | `ieum/skills/` |
| VS Code extension | `vscode-ieum/` |

---

## Development

```bash
# tests
python -m pytest -q

# extension build
cd vscode-ieum
npm run compile
```

---

## Documentation

- `docs/TUI_MODE.md`
- `docs/WEB_MODE.md`
- `docs/VSCODE_MODE.md`
- `docs/api.md`
- `docs/security.md`
- `docs/architecture.md`

---

## License

MIT
