User Guide

Welcome to the Agentrix User Guide. This documentation covers everything you need to use the Agentrix platform as an end user.

What is Agentrix?

Agentrix is an enterprise AI agent hosting and collaboration platform. It lets your team dispatch coding and analysis tasks to AI agents that run on your own machines, keeping source code and data under your control.

Core concepts

Concept	Description
Task	A unit of work sent from the web app or API to an agent
Daemon	A long-running background process that manages workers on your machine
Worker	A child process spawned by the daemon for each task (Claude, Codex, or other agent types)
Machine	A registered local environment bound to your Agentrix account
Workspace	An isolated directory where a worker runs each task

How it works

Web App / API
      │ WebSocket
      ▼
  Agentrix Backend
      │ WebSocket (machine channel)
      ▼
  Daemon  ──────── ~/.agentrix/logs/daemon.log
      │ spawn
      ▼
  Worker process  ──── ~/.agentrix/logs/worker-<taskId>.log
      │ git worktree / isolated workspace
      ▼
  Task result → synced back to backend

You create a task in the web app, linking it to a repository and selecting an agent type.
The backend sends the task over a WebSocket connection to the daemon running on your machine.
The daemon spawns a worker in an isolated workspace.
The worker (e.g. Claude Code) processes the task, commits results, and syncs them back.

Why Teams Choose Agentrix

AI agents move fast. Agentrix keeps your codebase, credentials, and workflow under your control while they do.

Execution stays local — Agents run on your own machine through the daemon. Repositories, secrets, and local tooling never leave your environment.
Tasks produce real code changes — Connect a repository, dispatch a task, and get back a reviewable commit — not a chat snippet.
Every task runs in isolation — Each task gets its own workspace, so parallel runs don't collide and experiments don't touch your main branch.
Fits your existing Git workflow — Review the diff, merge what you like, skip what you don't.
Desktop or CLI, your choice — Use the Desktop app for guided setup, or the CLI on Linux, servers, and CI/CD.
Execution is always visible — Machine status, logs, and task progress are available from the app and the command line.
Add sandbox isolation when you need it — Restrict worker filesystem and network access in more sensitive environments.

What teams use it for

Shipping features without blocking on repetitive implementation work
Debugging production issues with agents that can inspect the real repository
Refactoring and bulk changes in isolated workspaces, reviewed before merging
Running AI workers on laptops, shared machines, or headless servers

Choose Your Setup Path

How you install Agentrix depends on your operating system and use case.

Desktop App — macOS or Windows

The Desktop app is the recommended way for developers on macOS or Windows. It is a self-contained Electron application that:

Installs and manages its own Node.js runtime (no pre-installed Node.js required)
Guides you through installing all dependencies (Git, Claude CLI, ripgrep, etc.) via a UI
Manages the daemon through a system tray icon
Embeds the Agentrix web app directly in the window
Handles authentication via a native deep-link callback

→ Desktop App Setup (macOS / Windows)

CLI — Linux, servers, or CI/CD

The CLI is the right choice for Linux machines, headless servers, and automated pipelines. It requires Node.js 18+ and manual installation of dependencies.

npm install -g @agentrix/cli
agentrix start

→ CLI Setup (Linux / Server)

Directory Layout

Both the Desktop app and CLI store state under the same directory:

~/.agentrix/
├── credentials.json      — machine token (do not share)
├── settings.json         — daemon and sandbox configuration
├── daemon.state.json     — running daemon metadata (PID, port, version)
├── workspaces/           — per-task isolated working directories
├── agents/               — installed custom agents
├── config/
│   ├── claude/           — Claude Code config scoped to Agentrix
│   ├── codex/            — Codex config scoped to Agentrix
│   └── gemini/           — Gemini config scoped to Agentrix
└── logs/
    ├── daemon.log
    └── worker-<taskId>.log

Override the root directory with the AGENTRIX_HOME_DIR environment variable.

Topic	Description
Desktop App Setup	Install and use the Desktop app on macOS or Windows
CLI Setup	Install and use the CLI on Linux or in CI/CD
Dependencies	CLI dependency details (git, claude, sandbox tools)
CLI Commands	Full CLI command reference
Settings	Configure the daemon, sandbox, and environment
Troubleshooting	Diagnose and fix common problems
agentrix-run	Submit Agentrix CI runs from GitHub Actions, GitLab CI, or a shell
Private Cloud Setup	Deploy and manage private cloud runners on team-owned servers
Web App Workflows	Create chats and tasks, choose execution targets, and review agent output
Repository Workflows	Work from GitHub or GitLab repos, issues, merge requests, and inbox items
Agent Community	Discover, install, publish, review, and discuss agents and skills
Account, Billing, and API Keys	Manage profile, credits, subscriptions, machines, preferences, and API keys

What is Agentrix?​

Core concepts​

How it works​

Why Teams Choose Agentrix​

What teams use it for​

Choose Your Setup Path​

Desktop App — macOS or Windows​

CLI — Linux, servers, or CI/CD​

Directory Layout​

Further Reading​