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:
- Location — the EKOS home, where projects and their compiled knowledge live (default
~/.ekos, on WindowsC:\Users\<you>\.ekos), and whether to putekoson yourPATH. - 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.
- First project — a name and the directories it reads. EKOS never writes into them.
- 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.
- 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.
- 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.shinstalls 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) andzstdcompile 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.