docs

Getting started

dex is a terminal coding agent. You say what you want, it reads your code, edits files, runs tests, and leaves a clean diff — using your own API keys, your own models, in your own terminal.

Install

Prebuilt static binaries ship for x86_64/aarch64 Linux (musl — runs on any distro), macOS, and Windows: 

curl -fsSL https://raw.githubusercontent.com/sumofbytes/dex/HEAD/scripts/install.sh | sh
  • Pin a version: append 0.2.0 after sh (… | sh -s -- 0.2.0).
  • Custom directory: DEX_INSTALL_DIR=/usr/local/bin curl -fsSL … | sh.
  • Windows: grab dex-v*-*-x86_64-pc-windows-msvc.zip from the releases page.

Building from source instead: cargo build --release needs any Rust toolchain (edition 2021). The name dex collides with an unrelated crates.io crate, so GitHub releases + the install script are the distribution channel — cargo install gets you the wrong crate.

Configure a provider

dex runs with no config and refuses to guess a model: the first start prints a setup guide. Only one thing is required — a model selection and a key for its provider. A minimal ~/.config/dex/config.yaml: 

providers:
  opencode:
    api_key: sk-...        # the deposit place for this provider's key
model: zen/gpt-5.6-luna    # endpoint-or-provider / model

model: is the only selection knob and names provider and model. Built-in options include any models.dev provider with an OpenAI-style endpoint, Anthropic's native wire (model: anthropic/claude-sonnet-4-5 with ANTHROPIC_API_KEY), and ChatGPT-backed Codex OAuth.

The daemon bootstraps the models.dev catalog in the background on first start, so no manual steps are needed. dex doctor prints every resolved value with its origin — run it whenever setup misbehaves.

First run

cd your-project
dex

That launches the interactive TUI (and a background daemon). Ask for something concrete: 

> read src/main.rs and summarize what it does
> fix the failing test in tests/cli.rs and run the suite

The transcript streams live; tool calls and results appear as they happen. dex starts from the directory you launched it in — that directory is the agent's workspace, and file tools are confined to it.

Other ways to run

  • One-shot — dex "explain the Cargo.toml dependencies": a single answer, no TUI.
  • One-shot tool — dex run read path=Cargo.toml limit=40: execute one tool without any model round trip; scripts can stitch pipelines with $DEX_BIN.
  • Raw tool mode — pipe JSON tool calls into dex --tool.
  • Client–daemon — dex serve on one machine, dex connect http://host:8420 from anywhere. See the client–daemon guide.

TUI basics

  • Enter submits; Shift+Enter / Ctrl+J inserts a newline.
  • Tab autocompletes slash commands, providers, and models.
  • While dex works, keep typing: Enter queues a steering message (delivered before the next model call), Alt+Enter queues a follow-up.
  • Esc / Ctrl+C cancels the active turn; Ctrl+D on an empty line quits.
  • ! prefix runs a shell command directly — !cargo test output feeds the next turn; !!cmd stays visible but never reaches the model.
  • /help, /model, /permissions, /session — the common slash commands; unknown commands print a hint.

Permissions

Tools default to trusted (no approval popups). For guarded operation set DEX_PERMISSION=ask-writes or --permission ask-shell: writes and shell commands open an approval overlay with Allow once / Allow for this session / Deny. Paths stay confined to the workspace either way.

Session persistence

Every conversation journals to a crash-safe JSONL file under ~/.local/share/dex/sessions. A fresh session starts by default; --session <path> continues one, and quitting the TUI prints the exact resume command. See the sessions guide.

Troubleshooting

  • Refuses to start / no model — no layer selected one. Set model: in the config, DEX_MODEL, or --model; then dex doctor shows what resolved.
  • Auth errors — the key must live where the daemon's environment can see it (config providers.<name>.api_key or the provider's own env var like ANTHROPIC_API_KEY).
  • Wrong endpoint or wire protocol — pin base_url: under the provider; protocol fallback (responses → completions) is learned per endpoint+model automatically.
  • More logs — DEX_LOG=debug (provider requests/responses, tool runs); trace adds raw SSE lines.

Update & uninstall

dex update replaces the running binary with the latest release (SHA256-verified, atomic rename); dex update --all also refreshes the model catalog. Uninstalling is removing the binary and ~/.local/share/dex — dex keeps no other state.