CLI Setup (Linux / Server / CI)

Use the CLI when running Agentrix on a Linux machine, headless server, or CI/CD pipeline.

macOS or Windows desktop? Use the Desktop App instead — it handles all installation steps automatically.

Prerequisites

Requirement	Notes
Node.js 18+	Required to install and run the CLI
npm	Used to install the CLI globally
Git	Required for all tasks
Claude Code CLI	Required for Claude agent tasks; see Dependencies
Agentrix account	Sign up at agentrix.xmz.ai

Install

npm install -g @agentrix/cli

Verify:

agentrix --version

Then install the required external tools:

# Install Claude Code CLI (required for most tasks)
npm install -g @anthropic-ai/claude-code

# Linux sandbox dependencies
sudo apt install bubblewrap socat   # Debian / Ubuntu

See Dependencies for all platform-specific details and alternatives.

Authenticate

On first run, agentrix start needs to bind this machine to your account.

Run:

agentrix start

The CLI will:

1. Generate a unique machine ID.
2. Print a URL and attempt to open it in your default browser.
3. Wait while you complete the OAuth flow.
4. Store the token in ~/.agentrix/credentials.json and start the daemon.

Web Authentication

Opening your browser...
✓ Browser opened

Complete authentication in your browser window.

If the browser did not open, please copy and paste this URL:
https://agentrix.xmz.ai/auth/machine?...

Waiting for authentication...

If the browser does not open automatically, copy the URL and open it in any browser where you are logged in to your Agentrix account.

Check Status

agentrix status

Shows daemon state (PID, port, CLI version) and authentication status.

🤖 Daemon Status
✓ Daemon is running
  PID: 12345
  CLI Version: 1.2.3
  HTTP Port: 51234

🔐 Authentication
✓ Authenticated (credentials found)

Log Out

agentrix logout

Removes ~/.agentrix/credentials.json. The next agentrix start triggers authentication again.

State Directory

Path	Purpose
~/.agentrix/credentials.json	Machine token — keep this private
~/.agentrix/credentials/	Encrypted credentials such as private GitLab PATs, webhook secrets, and pipeline trigger tokens
~/.agentrix/settings.json	Daemon and sandbox configuration
~/.agentrix/daemon.state.json	Running daemon metadata
~/.agentrix/workspaces/	Isolated per-task working directories
~/.agentrix/agents/	Installed custom agents
~/.claude/settings.json	Claude Code config
~/.codex/config.toml	Codex config
~/.agentrix/config/gemini/	Gemini config isolated to Agentrix
~/.agentrix/logs/daemon.log	Daemon log file
~/.agentrix/logs/worker-<taskId>.log	Per-task worker log

Override the root with AGENTRIX_HOME_DIR:

export AGENTRIX_HOME_DIR=/opt/agentrix
agentrix start

Upgrade

agentrix upgrade

Runs npm install -g @agentrix/cli@latest and restarts the daemon if it was running.

agentrix start does not check for CLI updates; run agentrix upgrade when you want to update the CLI manually.

Next Steps

• Dependencies — install git, Claude Code, and Linux sandbox tools
• CLI Commands — full command reference
• Settings — configure the daemon, sandbox, and environment