Agentrix

01. Setup & Onboarding

Getting Started

Agentrix is local-first by default. Follow this checklist to set up your environment and run the agent runtime on your machine.

Create Virtual Environment

Set up an isolated python sandbox in the project root directory.

python3 -m venv .venv

Install Packages

Install the core runtime, relay agent gateway, and CLI tool in editable mode.

.venv/bin/pip install -e "./packages/core[all]" -e "./packages/relay" -e "./apps/cli"

Bring Your Own Key

./.venv/bin/agentrix login

Launch the Backend Relay

Start the WebSocket/FastAPI service so the web dashboard or mobile app can coordinate.

./.venv/bin/agentrix relay

Defaults to port 8765 on localhost.

02. Command Line Interface

CLI Commands Reference

The `agentrix` command is the control panel of the runtime. Run it from your project shell:

agentrix relay

Launch the local WebSocket relay. Links your computer workspace to frontends.

agentrix pair

Initialize a new session and generate a terminal-based QR code to scan on mobile or paste into the web connect screen.

agentrix run "[goal]"

Execute a single coding task in one-shot mode (e.g. "Fix the lint warnings in utils/helper.py") and stream events directly to stdout.

agentrix chat

Open the interactive console chat TUI directly in the terminal using the Textual framework.

agentrix index [subcommand]

Manage the semantic index database of your codebase folders for file/context lookup.

03. How it Works

Platform Architecture

Agentrix is structured as a decoupled multi-surface stack. A single runtime drives your workflow across all environments:

Core Runtime

Resides in `packages/core`. Acts as the brain. Manages prompt structures, token bounds, self-critique/eval loops, and registers system tools.

Relay Server

Resides in `packages/relay`. A lightweight FastAPI server connecting codebases to client surfaces over secure WebSockets.

Thin Clients

Includes Next.js 14 Dashboard, Expo React Native Mobile, and VS Code/Cursor plugins. Interacts directly with the relay.

⚡ PRO TIP: Every dangerous action (like write_file or shell commands) must pass an approval gate before executing. Approve via phone, VS Code panel, or the web dashboard.

04. Environment variables

Environment Configuration

Configure the stack behaviour by creating a `.env` file in the workspace root:

Variable	Purpose	Default
AGENTRIX_HOST	Host IP for relay server listener.	`127.0.0.1`
AGENTRIX_PORT	Port number for relay.	`8765`
AGENTRIX_LLM_DEFAULT_PROVIDER	Default LLM model provider.	`openai`
AGENTRIX_STORAGE_URL	SQLite path or PostgreSQL connection string.	`sqlite:///...`

05. FAQ & Troubleshooting

Troubleshooting Guidelines

Port Conflict Errors (EADDRINUSE)

If port 3000, 3001, or 8765 is in use when attempting to start the dashboard, run the following command to free the port bindings:

kill -9 $(lsof -t -i :3000 -i :3001 -i :8765)

Relay reports offline / connection failure

Ensure the python virtual environment is activated and you ran agentrix relay. If you specify AGENTRIX_RELAY_AUTH_TOKEN in your root .env, make sure to enter the bearer token inside the web connection credentials screen.

SQLite Journal Size Warnings

Long-lived workspaces can write a large WAL SQLite journal. To clean it up, enter the sqlite database CLI or execute `VACUUM`. For production grade multi-user scaling, switch to PostgreSQL.