Installing EONYX: build, run, and configure

EONYX is a terminal AI agent for working with code, written in Go.
It connects straight to any OpenAI-compatible API.
OpenAI, OpenRouter, DeepSeek, Moonshot.
Or a local Ollama, llama.cpp or LM Studio server.
No telemetry, no OAuth.
One process, one binary.

1 📦 Requirements and installation

1.1 What you need

• Go 1.26+ to build from source. A prebuilt binary needs nothing.
• An API key for any OpenAI-compatible provider. A local model server needs no key at all.
• A terminal: Windows Terminal, PowerShell, any Linux shell, macOS Terminal.
• A licence. One key binds one machine, and it is verified at every startup.

1.2 Installation options

git clone https://github.com/eonyx-core/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

The interactive TUI opens.
With no config at any level, EONYX writes a working eonyx.json into the global directory itself.
It ships two DeepSeek models and one local Ollama one.
All that is left is 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 level overrides the one before it.

• 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, found by walking up from the current directory

Wherever the project config is found becomes the project root.
A service folder .eonyx for exports and logs appears inside it.
EONYX_GLOBAL_CONFIG, EONYX_GLOBAL_DATA and EONYX_CACHE_DIR override the paths.
eonyx info and eonyx config show what was loaded and from where.

2.1 A full eonyx.json example

This is the default config written on the first run.
It carries 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 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"
  }
}

api_key and base_url may reference environment variables such as $OPENAI_API_KEY.
They expand after the layers merge, so no secret sits in the file.

A model binds an id to a provider:

max_steps caps the tool-call rounds inside one turn.
The default is 50.

2.3 Permissions

The safe tools are always allowed: read, ls, glob, grep, git_status, git_diff, git_log, todo_write.
Everything else needs permission: writing, editing, bash, commits, MCP tools.

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

• allowed_tools — tools that run without asking.
• sandbox — locks read, write, edit, multi_edit and ls inside the project root. Off by default.
• --yolo, or /yolo in the TUI — drops the gate for the whole session.

The TUI adds an interactive layer on top.
A tool outside the allowlist raises an Allow once / Allow always (this session) / Deny dialog.
A denial does not kill the turn: the model gets a tool error and adapts.

2.4 Hooks

Hooks are shell commands around tool calls.
The format is 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 first. A non-zero exit code blocks the call.
• after runs on success. Its output is appended to the tool result, so the model sees it. An error there does not break the result.
• Context arrives through environment variables, never substituted into the command text. Injection through the input 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, in the same shell session the bash tool uses.

2.5 Other keys

3 📋 Summary