Skip to main content

Self-Hosted Setup

Run Distri on your own infrastructure with full control over data and configuration.

Prerequisites​

  • A machine with at least 2GB RAM
  • Network access for LLM API calls (OpenAI, Anthropic, etc.)
  • Environment variables for your LLM provider

1. Install Distri​

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

Or pin a specific version:

DISTRI_VERSION=0.2.2 sh -c "$(curl -fsSL https://distri.dev/install.sh)"

2. Configure Environment​

Create a .env file or export environment variables:

# Required: LLM API keys
export OPENAI_API_KEY="sk-..."
# Or for Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

# Optional: Server configuration
export DISTRI_HOST="0.0.0.0"
export DISTRI_PORT="8787"

3. Create Your Agent​

Create an agents directory and add your agent definition:

mkdir agents

Create agents/assistant.md:

---
name = "assistant"
description = "A helpful assistant"

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

# ROLE

You are a helpful assistant. Answer questions clearly and concisely.

4. Start the Server​

distri serve

Options:

  • --port 8080 — Custom port (default: 8787)
  • --ui — Enable web interface
  • --config path/to/distri.toml — Custom config file

The server will:

  • Create a SQLite database at .distri/distri.db
  • Load agents from the agents/ directory
  • Expose HTTP and SSE endpoints

5. Test Your Agent​

Using CLI​

distri run assistant --task "Hello, world!"

Using HTTP API​

curl -X POST http://localhost:8787/agents/assistant \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/send",
    "params": {
      "message": {
        "kind": "message",
        "role": "user",
        "parts": [{"kind": "text", "text": "Hello!"}]
      }
    }
  }'

6. Integrate with Your Product​

For self-hosted, point the SDK to your server:

import { DistriProvider, Chat } from '@distri/react';

function App() {
  return (
    <DistriProvider
      config={{
        baseUrl: 'http://localhost:8787/v1'
      }}
    >
      <Chat agentId="assistant" />
    </DistriProvider>
  );
}

Configuration File​

Create a distri.toml for advanced configuration:

[server]
host = "0.0.0.0"
port = 8787

[database]
path = ".distri/distri.db"

[logging]
level = "info"

Data Storage​

All data is stored in a SQLite database at .distri/distri.db. This includes:

  • Threads — Conversation contexts
  • Tasks — Agent invocations
  • Sessions — Key-value state per thread
  • Secrets — Encrypted environment variables

See Database Schema for details on querying this data.

Next Steps​