Installing EONYX: build, run, and configure

EONYX is a terminal AI agent for working with code, written in Go. It connects directly to any OpenAI-compatible API (OpenAI, OpenRouter, DeepSeek, Moonshot, local Ollama / llama.cpp / LM Studio) — no external services, no telemetry, no OAuth. One process, one binary, everything local. Here: installation, the first run, and the full configuration.

1 Requirements and installation

1.1 What you need

• Go 1.26+ — to build from source (prebuilt binaries don’t need it).
• An API key for any OpenAI-compatible provider — or a local model server (Ollama, llama.cpp, LM Studio), in which case no key is needed.
• A terminal: Windows Terminal / PowerShell, any Linux shell, macOS Terminal.

1.2 Installation options

git clone https://github.com/avtotor/eonyx
cd eonyx
make build        # builds bin/eonyx with the version from the git tag

make install

eonyx --version

1.3 First run

cd my-project
eonyx

An interactive TUI chat opens. If there is no configuration at any level yet, EONYX creates a working eonyx.json in the global directory itself — with two DeepSeek models and one local one (Ollama). All that’s left is to set the key:

export DEEPSEEK_API_KEY=sk-...   # or your own provider, see below

eonyx run "describe what this repository does"
eonyx run -m deepseek-v4-pro --yolo "fix the failing test"

{ echo "explain the error:"; cat error.log; } | eonyx run

1.4 The remaining subcommands

1.5 Keys and commands in the TUI

Slash commands: /new, /clear, /add [path], /rename <title>, /fork, /export, /yolo, /plan, /timestamps, /model, /sessions [query], /help, /quit.

2 Configuration

EONYX reads eonyx.json from three levels and merges them top down — each next level overrides the previous one:

• Global config
  • Windows — %LOCALAPPDATA%\eonyx\eonyx.json
  • Linux/macOS — $XDG_CONFIG_HOME/eonyx/eonyx.json (~/.config/… by default)
• Global data
  • Windows — the same path
  • Linux/macOS — $XDG_DATA_HOME/eonyx/eonyx.json (~/.local/share/… by default)
• Project config
  • eonyx.json or .eonyx.json — searched for up the tree from the current directory

The directory where the project config is found becomes the project root: a service folder .eonyx (exports, logs) appears inside it. The paths can be overridden with the EONYX_GLOBAL_CONFIG, EONYX_GLOBAL_DATA, and EONYX_CACHE_DIR environment variables. To see what was loaded from where: eonyx info and eonyx config.

2.1 A full eonyx.json example

This is the default config EONYX creates on the first run — it contains every supported top-level key:

{
  "providers": {
    "deepseek": {
      "type": "openai",
      "base_url": "https://api.deepseek.com",
      "api_key": "$DEEPSEEK_API_KEY"
    },
    "local": {
      "type": "openai",
      "base_url": "http://localhost:11434/v1",
      "api_key": ""
    }
  },
  "models": [
    {"id": "deepseek-v4-flash", "provider": "deepseek", "context_window": 1000000, "input_price": 0.14, "output_price": 0.28},
    {"id": "deepseek-v4-pro", "provider": "deepseek", "context_window": 1000000, "input_price": 0.435, "output_price": 0.87},
    {"id": "qwen2.5-coder", "provider": "local", "context_window": 32768, "input_price": 0, "output_price": 0}
  ],
  "default_model": "deepseek-v4-flash",
  "max_steps": 50,
  "permissions": {
    "allowed_tools": []
  },
  "skills": [],
  "mcp": [],
  "hooks": {},
  "report": {
    "database_url": ""
  },
  "system_prompt": "",
  "log_file": "",
  "retry": {}
}

2.2 Providers and models

A provider is a way to reach an API. There is only one type so far — "openai" — and it covers any OpenAI-compatible endpoint:

"providers": {
  "openrouter": {
    "type": "openai",
    "base_url": "https://openrouter.ai/api/v1",
    "api_key": "$OPENROUTER_API_KEY"
  }
}

The api_key and base_url fields can reference environment variables ($OPENAI_API_KEY) — they are expanded after the layers are merged, so secrets are not stored in the file.

A model binds an id to a provider:

max_steps limits the number of tool-call rounds within a single turn (50 by default).

2.3 Permissions

The safe tools — read, ls, glob, grep, git_status, git_diff, git_log, todo_write — are always allowed. Everything else (writing, editing, bash, git commits, MCP tools…) requires permission:

"permissions": {
  "allowed_tools": ["bash", "write", "edit"],
  "sandbox": true
}

• allowed_tools — the list of tools that run without asking.
• sandbox — locks the file tools (read/write/edit/multi_edit/ls) inside the project root; off by default.
• --yolo (or /yolo in the TUI) — disables the gate entirely for the duration of the session.

In the TUI an interactive layer works on top of the static policy: for a tool that isn’t in the allowlist, EONYX shows an Allow once / Allow always (this session) / Deny dialog. A denial doesn’t kill the turn — the model receives it as a tool error and adapts.

2.4 Hooks

Hooks are shell commands around tool calls. The format: tool name → before / after:

"hooks": {
  "write": {
    "before": "echo \"writing: $EONYX_INPUT\" >> .eonyx/audit.log",
    "after":  "gofmt -l ."
  },
  "bash": {
    "before": "[ \"$EONYX_CWD\" = \"$HOME\" ] && exit 1 || exit 0"
  }
}

Rules:

• before runs before the tool; a non-zero exit code blocks the call.
• after runs after it; its output is appended to the tool result (the model sees it). Errors in after don’t break the result.
• Context is passed through environment variables rather than by substitution into the command text — injection via the input content is impossible:
  • EONYX_TOOL — the tool name
  • EONYX_PHASE — before / after
  • EONYX_CWD — the working directory
  • EONYX_INPUT — the JSON input
  • EONYX_RESULT — the result, only in after
• Each hook gets 30 seconds; hooks run in the same shell session as the bash tool.

2.5 Other keys

3 Summary