Contributing to Moxxy

Guidelines for building Moxxy from source, running tests, and contributing to the project.

Prerequisites

Tool	Version	Purpose
Rust	1.80+	Gateway and core engine
Node.js	22+	CLI and tooling
Git	any	Version control

Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup update

Install Node.js

Use your preferred method (nvm, fnm, or direct download):

# Using nvm
nvm install 22
nvm use 22

Building from Source

Gateway (Rust)

# Debug build
cargo build

# Release build (optimized)
cargo build --release

The gateway binary is the core of Moxxy, handling the API server, agent runtime, sandbox, and all backend logic.

CLI (Node.js)

npm install

Running Tests

Rust Tests

# Run the full test suite (646+ tests across all crates)
cargo test --workspace

# Run tests for a specific crate
cargo test -p moxxy-gateway

# Run a specific test by name
cargo test test_agent_creation

CLI Tests

# Run all CLI tests (80+ tests)
npm test

Running a Subset

# Run only integration tests
cargo test --workspace --test '*'

# Run only unit tests (lib targets)
cargo test --workspace --lib

Linting and Formatting

Rust

# Lint with Clippy
cargo clippy --workspace --all-targets -- -D warnings

# Format code
cargo fmt --all

# Check formatting without modifying files
cargo fmt --all -- --check

Node.js

# Lint
npm run lint

# Format
npm run format

Project Structure

moxxy/
  crates/
    moxxy-gateway/     # API server, routing, middleware
    moxxy-engine/      # Agent runtime, run loop, primitives
    moxxy-memory/      # Memory subsystem (STM, LTM, embeddings)
    moxxy-sandbox/     # OS sandbox, PathPolicy, allowlists
    moxxy-vault/       # Secret storage, grants, encryption
    moxxy-channels/    # Telegram, Discord channel integrations
    moxxy-wasi/        # WASI plugin runtime (wasmtime)
    ...
  cli/                 # Node.js CLI
  docs/                # Documentation (this site)

CI Pipeline

Moxxy uses GitHub Actions for continuous integration. The pipeline runs on every push and pull request:

1. Formatting check -- cargo fmt --all -- --check
2. Clippy lint -- cargo clippy --workspace --all-targets -- -D warnings
3. Rust tests -- cargo test --workspace
4. CLI tests -- npm test

All checks must pass before a pull request can be merged.

Development Workflow

1. Fork and clone the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes
4. Run the full test suite: cargo test --workspace && npm test
5. Run the linter: cargo clippy --workspace --all-targets -- -D warnings
6. Commit and push your branch
7. Open a pull request against main

Running Locally

Start the gateway in development mode:

# Build and run
cargo run --release

# Or with debug logging
RUST_LOG=debug cargo run

The API will be available at http://127.0.0.1:3000. In loopback mode (default), no authentication is needed for local requests.

Environment Variables

Variable	Description
MOXXY_PORT	API server port (default: 3000)
RUST_LOG	Log level (e.g., debug, info, moxxy_gateway=debug)
DATABASE_URL	Database connection string