Installation

Get Moxxy installed on your system.

Quick Install (Recommended)

Install the CLI globally via npm:

npm install --global @moxxy/cli

Then run the interactive setup wizard:

moxxy init

The moxxy init command will:

1. Walk you through LLM provider selection and API key configuration
2. Download the moxxy-gateway binary to ~/.moxxy/bin/
3. Scaffold the ~/.moxxy/ data directory
4. Start the gateway automatically

Requirements

Before installing, ensure you have:

Requirement	Purpose
macOS or Linux	Supported operating systems
Node.js 22+	Runtime for the @moxxy/cli package
An LLM API key	Anthropic, OpenAI, or a locally running Ollama instance

TIP

Moxxy runs entirely on your machine. Your data never leaves your infrastructure unless you explicitly configure external channel integrations.

Build from Source

For developers or contributors who want to build from the repository:

Prerequisites

• Rust 1.80+ -- Install Rust
• Node.js 22+ -- Required for the CLI package
• npm -- Comes with Node.js

Build Steps

# Clone the repository
git clone https://github.com/moxxy-ai/moxxy.git
cd moxxy

# Build the gateway binary
cargo build --release
# Binary will be at ./target/release/moxxy-gateway

# Install the CLI
cd cli
npm install
npm link

You can then copy the gateway binary to ~/.moxxy/bin/moxxy-gateway or point the CLI at it with the MOXXY_GATEWAY_URL environment variable.

Verify Installation

Check that the CLI is installed correctly:

moxxy --help

You should see the help output listing available commands like init, gateway, channel, and others.

Environment Variables

Moxxy respects several environment variables for customization:

Variable	Default	Purpose
MOXXY_HOME	~/.moxxy	Data directory for all Moxxy files
MOXXY_HOST	127.0.0.1	Gateway listen address
MOXXY_PORT	3000	Gateway listen port
MOXXY_LOOPBACK	true	Bypass auth for localhost requests
MOXXY_API_URL	(derived)	Override the gateway API URL
MOXXY_TOKEN	(none)	Bearer token for CLI-to-gateway auth
MOXXY_GATEWAY_URL	(none)	Custom gateway binary URL for download
MOXXY_DB_PATH	(derived)	Override the SQLite database path
MOXXY_VAULT_KEY	(none)	Override vault encryption key location
MOXXY_CORS_ORIGINS	(none)	Allowed CORS origins for the API

Next Steps

Once installed, proceed to the Quick Start to configure your LLM provider and create your first agent.

Troubleshooting

Node.js Version Too Old

Moxxy requires Node.js 22 or later. Check your version:

node --version

If you need to upgrade:

# Using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install 22
nvm use 22

# Using Homebrew (macOS)
brew install node@22

Permission Denied on Global Install

If npm install --global fails with permission errors:

# Option 1: Fix npm permissions (recommended)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
# Add ~/.npm-global/bin to your PATH in ~/.bashrc or ~/.zshrc
export PATH=~/.npm-global/bin:$PATH

# Option 2: Use npx without global install
npx @moxxy/cli init

Gateway Binary Download Fails

If the gateway binary fails to download during moxxy init:

1. Check your internet connection
2. Try downloading manually from the GitHub releases page
3. Place the binary at ~/.moxxy/bin/moxxy-gateway and make it executable: chmod +x ~/.moxxy/bin/moxxy-gateway

SQLite Errors on Linux

On some Linux distributions, you may need SQLite development headers for building from source:

# Ubuntu/Debian
sudo apt-get install libsqlite3-dev

# Fedora
sudo dnf install sqlite-devel

Upgrading

To upgrade the CLI to the latest version:

npm update --global @moxxy/cli

To upgrade the gateway binary, re-run:

moxxy init

Your agents and data in ~/.moxxy/ are preserved during upgrades.