EKOSdocs
Docs / Getting Started Build

Installation

Install EKOS on Linux, Windows 11 or macOS with the setup wizard and web console, the command alone, or from source.

EKOS ships prebuilt for Linux, macOS and Windows 11. Installing needs no Rust toolchain, no compiler and no administrator rights. Building from source is still supported and documented below.

Which release?

The installer and the prebuilt archives are the latest release, v1.2.0 (2026-11-04): the compiler pipeline, search, EKL, ekos ask, the MCP server, projects in the EKOS home, the setup wizard and the web console, and everything below, which v1.2.0 added to v1.1.0 (2026-10-14). Anything merged to main after a release comes with a build from source.

New in v1.2.0 Commands / config
Java source analyzer, iDempiere application model always on for .java files
Oracle dialect, PL/SQL, schema history from migration scripts [recover.sql] dialect oracle
Live database catalogs: Oracle, PostgreSQL, ClickHouse [[databases]], ekos database add|list|test|remove
Write behaviour per table, ticket links [tickets] keys
Source-model review and digest-bound sign-off, the seven-step bar ekos review, ekos signoff, ekos workflow status
Estate documentation ekos docs generate --layout estate
Cross-reference integrity check ekos check refs, ekos check explain, [xref]
JSON-lines run logs <state>/runs/, EKOS_RUN_LOG
Per-task model routes and recorded usage [llm.tasks.*], ekos llm routes|usage|probe
Backups to object storage ekos home backup --to, restore --from (container image)
Benchmarks: BIRD Text-to-SQL ekos eval bench prepare|run|context|compare|export (results)

A binary built from main reports the version of the last release until the next one is tagged, so the version number alone does not tell the two apart.

Install the release

Linux, macOS — installs everything and opens a setup page in your browser:

curl -fsSL https://raw.githubusercontent.com/alexeyban/EKOS/main/install.sh | sh

Windows 11 — the same, in PowerShell:

powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/alexeyban/EKOS/main/install.ps1 | iex"

Offline — download ekos-<version>-<target>-full (.tar.gz, or .zip on Windows) from the releases page, unpack it anywhere and start setup.sh (Linux), setup.command (macOS) or setup.cmd (Windows).

The command only, without the web console: see below.

Install scripts: install.sh · install.ps1 · all releases.

The setup wizard

The full package holds the ekos command, the web console and the Python that runs it; nothing else is needed. Installing it opens a setup page in your browser, which asks:

  1. Location — the EKOS home, where projects and their compiled knowledge live (default ~/.ekos, on Windows C:\Users\<you>\.ekos), and whether to put ekos on your PATH.
  2. Web console — Only me (local mode: this machine only, signed in with a one-time code) or A team (sign-in through your organisation's OIDC provider; a client secret goes to the system keychain, never to a file). The port, and limits for the per-project MCP servers.
  3. First project — a name and the directories it reads. EKOS never writes into them.
  4. Agents — register the project's MCP server with Claude Code, Claude Desktop or VS Code. Each config file is backed up first, and its other entries are kept.
  5. Chat (optional) — a model that answers questions about a project with its EKOS tools: a local Ollama model, Anthropic, or any OpenAI-compatible server. A key goes to the keychain.
  6. Start — start the console at login, start it now, open it.

Nothing changes until you confirm the list of steps on the last page. Afterwards everything — the console's settings, every project's ekos.toml, and every ekos command — is available in the console itself:

ekos console open | status | stop | start | restart | logs
ekos setup                  # change any of it later
ekos uninstall              # the program, login entry, PATH line, agent entries; keeps projects
ekos uninstall --purge --yes   # also every project and the console's database

To remove EKOS from the browser instead, open the console's Settings → Uninstall EKOS, or run ekos uninstall --ui: the page lists what will be removed and your projects with their size, and removes nothing until you type the confirmation word.

In the console, a project's Init & compile button runs every compiler stage — build, recover, resolve, compile, commit — and ends with a coverage report.

For a server or a script, ekos setup --answers answers.toml applies the same answers without a browser, and --dry-run lists the steps.

Not signed. On Windows, SmartScreen says "Windows protected your PC": choose More info → Run anyway. On macOS, right-click setup.command → Open the first time.

Full packages exist since v1.1.0 for Linux (x86_64, ARM 64-bit), macOS on Apple silicon and Windows 11. On an Intel Mac install.sh installs the command only: a library the console needs no longer ships for Intel macOS.

Install the command only

curl -fsSL https://raw.githubusercontent.com/alexeyban/EKOS/main/install.sh | EKOS_CLI_ONLY=1 sh

This puts a single ekos binary in the EKOS home, ~/.ekos/bin, and creates ~/.ekos/data, where projects keep their config and compiled data. EKOS_HOME moves the home; EKOS_INSTALL_DIR puts the binary elsewhere (an earlier install in ~/.local/bin is upgraded where it is). The script resolves the latest release, verifies the download against that release's SHA256SUMS before unpacking it, and never uses sudo. EKOS_VERSION=v1.2.0 pins a release.

Piping a script into a shell is a real supply-chain decision, so the script is short enough to read first:

curl -fsSL https://raw.githubusercontent.com/alexeyban/EKOS/main/install.sh -o install.sh
less install.sh && sh install.sh

Download it by hand

Every release is a plain archive on the releases page.

Your machine Asset
Linux, Intel/AMD 64-bit ekos-<version>-x86_64-unknown-linux-gnu.tar.gz
Linux, Intel/AMD, older distro ekos-<version>-x86_64-unknown-linux-musl.tar.gz
Linux, ARM 64-bit ekos-<version>-aarch64-unknown-linux-gnu.tar.gz
macOS, Apple Silicon ekos-<version>-aarch64-apple-darwin.tar.gz
macOS, Intel ekos-<version>-x86_64-apple-darwin.tar.gz
Windows, 64-bit ekos-<version>-x86_64-pc-windows-msvc.zip

uname -sm tells you which row you are on. Take the gnu build first; if it refuses to start with version 'GLIBC_2.x' not found, your distribution is older than the machine the release was built on — use the musl build, which is fully static. (install.sh falls back on its own.)

VERSION=v1.2.0
TARGET=x86_64-unknown-linux-gnu
ASSET="ekos-${VERSION#v}-$TARGET.tar.gz"
BASE="https://github.com/alexeyban/EKOS/releases/download/$VERSION"

curl -fsSLO "$BASE/$ASSET"
curl -fsSLO "$BASE/SHA256SUMS"

# Verify before unpacking. One line keeps it quiet about the assets you did not
# download, and works with GNU sha256sum and macOS shasum alike.
grep "$ASSET" SHA256SUMS | sha256sum -c -        # macOS: shasum -a 256 -c -

tar xzf "$ASSET"
mkdir -p ~/.local/bin                            # install(1) will not create it
install -m 755 "ekos-${VERSION#v}-$TARGET/ekos" ~/.local/bin/ekos

That prints <asset>: OK and exits 0. Anything else means do not unpack it.

Releases are checksummed but not signed — no Sigstore/cosign signature or SLSA provenance yet. SHA256SUMS shows the archive arrived intact; it does not, by itself, prove who built it.

On Windows, download the .zip, check it with Get-FileHash -Algorithm SHA256, expand it, and put ekos.exe on your PATH.

macOS only. These binaries are not signed or notarised, so a file downloaded through a browser is quarantined by Gatekeeper and refuses to run. Clear the flag:

xattr -d com.apple.quarantine ~/.local/bin/ekos

Downloading with curl, as above, does not set that flag — this applies only if you clicked the link in a browser.

Upgrading and removing

Re-run the install command to replace EKOS with the latest release (it installs a tagged release, never main; a source build is upgraded with git pull and cargo install again). A full install is removed with ekos uninstall (add --purge --yes to delete projects too). A command-only install is removed by deleting the binary (rm ~/.ekos/bin/ekos) and, if you want, the home ~/.ekos.

Build from source

Still fully supported, what you want if you are contributing, and how you get what has been merged to main since the latest release.

The Cargo workspace root is ekos/, not the repository root — there is no top-level Cargo.toml.

Two optional features are off in a default build:

Feature Adds Needs
oracle the live Oracle driver for [[databases]] kind = "oracle"; without it such an entry fails ekos build with a message saying so a C compiler to build, Oracle Instant Client on LD_LIBRARY_PATH at run time
object-storage ekos home backup --to / ekos home restore --from with S3, Azure Blob or Google Cloud Storage (the container image is built with it) nothing extra
cargo install --path crates/cli --features oracle,object-storage

PostgreSQL and ClickHouse databases need no feature and nothing installed.

Prerequisites

  • Rust, via rustup. The repository pins its toolchain in rust-toolchain.toml, so rustup installs the right version automatically.
  • A C/C++ toolchain. The bundled SQLite (rusqlite) and zstd compile native C at build time.
  • Git, to clone.

macOS

xcode-select --install
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
git clone https://github.com/alexeyban/EKOS.git
cd EKOS/ekos
cargo build --release --workspace
cargo install --path crates/cli

Linux

Install a C toolchain (sudo apt install build-essential on Debian/Ubuntu), then follow the macOS steps from the rustup line.

Windows 11

WSL2 is the path of least friction: wsl --install, open the Ubuntu shell, and follow the Linux steps. Native Windows also works:

winget install Microsoft.VisualStudio.2022.BuildTools --override "--add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"
winget install Rustlang.Rustup
winget install Git.Git
git clone https://github.com/alexeyban/EKOS.git
cd EKOS\ekos
cargo build --release --workspace
cargo install --path crates\cli

Verify

ekos --version
ekos --help
ekos doctor        # checks environment and configuration

ekos doctor reports the configured LLM provider and endpoint, and whether the API-key variable is set. Once a workspace has been compiled it also reports coverage — whether every input kind present actually produced objects — and fails if any produced none. ekos doctor --json emits the same checklist as one JSON object.