docs
Installation
Install the Ninetrix CLI and set up your local development environment.
Ninetrix requires Docker Desktop, Python 3.11+, and an API key for your LLM provider.
Prerequisites
| Requirement | Version | Notes |
|---|---|---|
| Docker Desktop | 4.0+ | Must be running before ninetrix dev |
| Python | 3.11+ | For the CLI and local packages |
| Node.js | 18+ | Only needed for MCP servers that use npx |
| LLM API key | — | Anthropic, OpenAI, Google, Mistral, or Groq |
Install the CLI
The recommended way to install is the one-liner, which auto-detects pipx, uv, or pip3 and picks the best option:
Bash
curl -fsSL https://install.ninetrix.io | sh
Or install manually:
Bash
# pip
pip install ninetrix
# uv
uv tool install ninetrix
See ninetrix on PyPI for all versions and release notes.
Bash
# Verify installation
ninetrix --version
Start the local stack
ninetrix dev pulls Docker images and starts the core local stack. The MCP gateway and worker are opt-in:
Bash
ninetrix dev # core stack; prompts for MCP
ninetrix dev --mcp # core stack + MCP gateway + worker
| Service | Port | Purpose |
|---|---|---|
| PostgreSQL | 5432 | Stores agent checkpoints and run history |
| API server | 8000 | REST API + local dashboard at /dashboard |
| MCP gateway | 9090 | Routes tool calls to MCP workers (opt-in via --mcp) |
| MCP worker | — | Runs MCP server subprocesses (opt-in via --mcp) |
First run
On first run,
ninetrix dev creates ~/.agentfile/mcp-worker.yaml (empty servers list) and generates ~/.agentfile/.api-secret (machine auth token). These persist across restarts.Environment variables
Create a .env file in your project directory. Ninetrix forwards these to the agent container at runtime:
.env
# LLM providers (set the one you use)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GEMINI_API_KEY=...
DEEPSEEK_API_KEY=...
MISTRAL_API_KEY=...
GROQ_API_KEY=...
TOGETHERAI_API_KEY=...
OPENROUTER_API_KEY=...
CEREBRAS_API_KEY=...
FIREWORKS_API_KEY=...
MINIMAX_API_KEY=...
# AWS Bedrock (uses IAM credentials instead of API key)
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION_NAME=us-east-1
# Azure OpenAI
AZURE_API_KEY=...
AZURE_API_BASE=https://your-resource.openai.azure.com
AZURE_API_VERSION=2024-02-01
# Local stack (set automatically by ninetrix dev)
AGENTFILE_API_URL=http://localhost:8000
AGENTFILE_RUNNER_TOKEN=<from ~/.agentfile/.api-secret>
# Telemetry (enables session memory and crash recovery)
# AGENTFILE_API_URL and AGENTFILE_RUNNER_TOKEN are set automatically by ninetrix dev
# MCP tool credentials
GITHUB_TOKEN=ghp_...
SLACK_BOT_TOKEN=xoxb-...
BRAVE_API_KEY=BSA...
Verify the setup
Bash
ninetrix status # check container health
ninetrix doctor # diagnose common issues