Getting Started

Distri lets you define an agent once in a markdown file and reach it from the CLI, an API, or embedded in your product. In the next few minutes you'll install the CLI, write an agent, push it to your workspace, and run it. Then you'll be ready to drop it into your app.

By default the CLI connects to Distri Cloud at api.distri.dev, so there's no infrastructure to stand up. Prefer to run everything on your own machine? See Run Distri locally.

---

1. Install the CLI

curl -fsSL https://distri.dev/install.sh | sh
distri --version

The installer downloads a prebuilt binary for macOS and Linux (x86_64 / arm64). On other platforms it offers to build from source with Cargo (installing Rust first if needed), and asks before doing either. Pass -y for a non-interactive install.

2. (Optional) Teach your coding agent

If you build with Claude Code, Cursor, or Codex, install the Distri skill so your agent writes correct distri commands for you:

curl -fsSL https://distri.dev/skills/install.sh | sh

See Distri skill for coding agents.

3. Write your first agent

An agent is a markdown file with a TOML frontmatter block. Create agents/assistant.md:

---
name = "assistant"
description = "A concise, helpful assistant"
max_iterations = 3

[tools]
builtin = ["final"]

[model_settings]
model = "gpt-4.1-mini"
---

# ROLE
You are a concise, helpful assistant. Answer clearly and get to the point.

That's the whole agent: who it is (# ROLE), what it can do ([tools]), and which model runs it ([model_settings]). The final built-in lets it return an answer.

Set your model key

Distri uses your model provider key. Export it before running:

export OPENAI_API_KEY="sk-..."

4. Push it to your workspace

First authenticate. The quickest way is an interactive login:

distri login

For CI or a scripted setup, skip the login and set your workspace credentials in the environment instead. A .env file works well:

# .env
DISTRI_API_KEY=dak_your_key
DISTRI_WORKSPACE_ID=your-workspace-id
# DISTRI_BASE_URL defaults to https://api.distri.dev

Then push the whole project tree:

distri push          # syncs agents/, skills/, and templates/

Your agent now lives in your workspace, ready to run or call from a product.

5. Run it

distri run --task "Explain what an AI agent is, in two sentences." --agent assistant

Or drop into the interactive TUI to chat and switch between agents:

distri

That's a working agent. Everything else, like tools and embedding, builds on this same file.

---

Next: give it your product's tools

The main use case for Distri is giving an agent your product's own functions as tools, so it can act inside your app: fill a form, update a grid, drive the page. From there, embed a streaming chat with a few lines of React or Angular.

In-Product ToolsGive the agent your product's functions to drive your UIUsing Distri in your productSet up the client, render a chat (React & Angular)Live SamplesAgents driving real product UIsRun Distri locallyEverything on your own machine instead

---

Distri is fair-code licensed and free to self-host. The source and license are on GitHub.