Skip to main content

Run Distri locally

By default the CLI and the SDK talk to Distri Cloud at api.distri.dev. This guide runs the whole stack on your own machine instead, with no account and no cloud. It's the fastest way to build and iterate on agents.

If you haven't installed the CLI yet, start with Getting Started; this page picks up from a working distri and a project with an agents/ folder.

Serve your agents​

From a directory with an agents/ folder, start the server:

export OPENAI_API_KEY="sk-..."   # your model provider key
distri serve

This exposes your agents over an A2A-compatible JSON-RPC API with SSE streaming, listening on :7777 by default (use --port to change it). It's the same interface the React SDK talks to.

Point the CLI at it​

Set DISTRI_BASE_URL so the CLI targets your local server instead of the cloud:

export DISTRI_BASE_URL="http://localhost:7777"
distri run --task "Hello" --agent assistant

Or pass --base-url http://localhost:7777 on any command.

Point the SDK at it​

Give DistriProvider your local URL, no tokens needed against a local server:

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

function App() {
  return (
    <DistriProvider config={{ baseUrl: 'http://localhost:7777' }}>
      <Assistant />
    </DistriProvider>
  );
}

function Assistant() {
  const { agent } = useAgent({ agentIdOrDef: 'assistant' });
  if (!agent) return <div>Loading…</div>;
  return <Chat threadId="my-conversation" agent={agent} enableHistory />;
}

Call the API directly​

Any client can hit the JSON-RPC endpoint. Here's a raw message send:

curl -X POST http://localhost:7777/v1/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!" }]
      }
    }
  }'

Next steps​

  • Setup: configuration and deployment options for the server.
  • Database: configure persistent storage.
  • Distri Cloud: skip the ops and let us host it.