// SimulAI.dev

The developer platform for AI simulation tools. Spawn agents, run sandboxes, inspect traces — from your terminal.

TS getting-started.ts
                                
                                
                            

                            1import { Simulator, Agent } from 'simulai';
2
3// Boot a sandboxed simulation worker
4const sim = new Simulator({ seed: 42, parallelism: 8 });
5
6const agent = new Agent({ model: 'gpt-5o', temperature: 0.7 });
7
8const trace = await sim.run(agent, {
9  task: 'Plan a 3-step Mars supply mission',
10  maxSteps: 25,
11});
12
13console.log(trace.summary);
14// → { steps: 25, tokens: 4180, cost: $0.012 }
                        

## Why simulai

Most agent frameworks ship a runtime. We ship the "flight recorder". Every tool call, every token, every retry — captured, replayable, diff-able. Build agents the way devs build software: with tests, traces, and CI.

// 01

deterministic()

Same seed, same trace. Snapshot agents and replay them across model upgrades.

// 02

parallel()

Run thousands of trajectories on a single box. Aggregate metrics, find regressions.

// 03

inspect()

Drop into any step, edit prompt, fork the timeline. Like a debugger for cognition.

// 04

deploy()

Ship the same simulator binary to prod. No rewrites, no frameworks, no leak.

## Install

SimulAI ships as a single static binary plus language bindings for TypeScript, Python, and Rust.

SH install.sh
                                
                                
                            

                            1# macOS / Linux
2curl -fsSL https://simulai.dev/install.sh | sh
3
4# or via npm
5npm install -g simulai
6
7# verify
8simulai --version
9# → simulai 1.4.2 (catppuccin)
                        

## System requirements

os:macOS 13+, Linux (glibc 2.31+), Windows 11 WSL2
runtime:Node 20+, Python 3.10+, Rust 1.74+
memory:4 GB minimum, 16 GB recommended for parallel sims
network:outbound https for model providers (offline mode available)

## Configuration

Drop a simulai.config.json at your project root. The simulator reads it on every simulai run.

{} simulai.config.json
                                
                                
                            

                            1{
"$schema": "https://simulai.dev/schema/v1.json",
"project": "mars-supply-agent",
"seed": 42,
"parallelism": 8,
"providers": {
  "openai": { "key": "$OPENAI_API_KEY" },
  "anthropic": { "key": "$ANTHROPIC_API_KEY" }
},
"tracing": { "export": "otlp", "redact": true },
"budget": { "usd": 5.00, "steps": 10000 }
12}
                        

## API reference

The TypeScript SDK exposes three primitives: Simulator, Agent, and Trace. Everything else composes from those.

Method Signature Returns

sim.run() (agent, opts) Promise<Trace>

sim.replay() (traceId) Promise<Trace>

sim.fork() (trace, stepIdx) Promise<Trace>

agent.use() (tool: Tool) Agent

trace.diff() (other: Trace) DiffReport

trace.export() (fmt: 'otlp' | 'json') Buffer

## CLI commands

simulai run—execute a config and stream traces
simulai inspect <id>—open a trace in the TUI debugger
simulai diff a b—compare two traces side-by-side
simulai bench—run a suite, emit junit + flamegraph