Skip to content

Installation

Maelstrom is distributed as scoped packages so you can install only the layers your app needs. Most React apps start with @maelstrom-co/react in the browser and @maelstrom-co/engine on the server.

Packages

Section titled “Packages”
Package Purpose
@maelstrom-co/react React bindings — createMaelstrom(), vessel(), hooks, Provider, Chart
@maelstrom-co/client Framework-agnostic client — Orchestrator, connectors, managers
@maelstrom-co/protocol Shared types, Zod schemas, message definitions
@maelstrom-co/engine Server-side LLM decision engine

Minimal installs by use case

Section titled “Minimal installs by use case”
Use case Install in the browser app Install on the server
React chart only @maelstrom-co/react An engine implementation, commonly @maelstrom-co/engine
Framework-agnostic client @maelstrom-co/client @maelstrom-co/protocol An engine implementation

@maelstrom-co/react depends on the client and protocol packages and re-exports the vessel definition helper plus connector classes (WebSocketConnector, HttpConnector) you need to connect to the engine, so React apps only need to install @maelstrom-co/react. Install @maelstrom-co/client separately only if you are building a framework-agnostic client.

Install

Section titled “Install”
Terminal window
# Client-side React app
npm install @maelstrom-co/react


# Server-side reference engine


npm install @maelstrom-co/engine

Peer dependencies

Section titled “Peer dependencies”

@maelstrom-co/react requires:

  • react >= 18.0.0
  • react-dom >= 18.0.0

Environment variables

Section titled “Environment variables”

The demo engine uses OpenAI. Set the following environment variables:

.env
ENGINE_MODEL=                  # Optional — defaults to gpt-6-luna
OPENAI_API_KEY=your-key        # Demo engine + realtime voice mint
OPENAI_REALTIME_MODEL=         # Optional — defaults to gpt-realtime-2.1
WS_PORT=3001                   # Optional — WebSocket port (defaults to 3001)

Next steps

Section titled “Next steps”