Quick Start

Get your first Moxxy agent running in under 5 minutes.

Step 1: Run the Setup Wizard

After installing the CLI, run the onboarding wizard:

moxxy init

The wizard uses an interactive terminal UI (powered by @clack/prompts) to guide you through:

1. LLM Provider Selection -- Choose your AI backend
2. API Key Configuration -- Enter your key securely (stored encrypted in the vault)
3. Gateway Download -- The moxxy-gateway Rust binary is downloaded to ~/.moxxy/bin/
4. Gateway Startup -- The gateway starts automatically and begins listening on port 3000

Supported LLM Providers

Provider	Models	Get API Key
Anthropic	Claude Sonnet, Claude Opus, Claude Haiku	console.anthropic.com
OpenAI	GPT-4o, GPT-4o-mini, o1, o3-mini	platform.openai.com
Ollama	Any local model (Llama, Mistral, etc.)	ollama.com (runs locally)
OpenAI-compatible	xAI/Grok, Google Gemini, DeepSeek	Varies by provider

TIP

Your API keys are stored encrypted in the vault using AES-GCM. They never leave your machine unless sent to the provider's API.

Step 2: Verify the Gateway

After moxxy init completes, the gateway should be running. Verify with:

curl http://127.0.0.1:3000/v1/health

You should see a healthy response. The gateway exposes a REST API at http://127.0.0.1:3000/v1/.

INFO

By default, loopback mode is enabled -- requests from localhost bypass bearer token authentication. This makes local development frictionless.

Step 3: Create an Agent

Create your first agent via the REST API:

curl -X POST http://127.0.0.1:3000/v1/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "assistant",
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514",
    "persona": "You are a helpful AI assistant. You are thorough, concise, and prefer concrete examples."
  }'

This creates an agent with:

• A sandboxed workspace at ~/.moxxy/agents/{id}/workspace/
• A memory journal directory at ~/.moxxy/agents/{id}/memory/
• An allowlist of permitted primitives
• Access to the configured LLM provider

Step 4: Start a Run

Send a prompt to your agent to start a run:

curl -X POST http://127.0.0.1:3000/v1/agents/assistant/runs \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Hello! List the files in your workspace and tell me what you can do."
  }'

The agent will reason through the task using its LLM and available primitives (like fs.list, shell.exec, etc.), then return a response.

Step 5: Stream Events (Optional)

To watch agent activity in real time, connect to the SSE event stream:

curl -N http://127.0.0.1:3000/v1/events/stream

This streams 60 event types covering runs, messages, primitive calls, memory operations, skill execution, and more.

Directory Structure

After setup, Moxxy creates the following structure in ~/.moxxy/:

~/.moxxy/
├── moxxy.db              # SQLite WAL database (single DB for everything)
├── vault.key             # 32-byte AES encryption key (0600 perms)
├── bin/
│   └── moxxy-gateway     # Gateway binary (auto-downloaded)
├── config/
│   ├── gateway.yaml      # Gateway configuration
│   └── channels.yaml     # Channel definitions (Telegram, Discord)
├── logs/                 # Gateway log files
└── agents/{id}/
    ├── workspace/        # Sandboxed working directory
    ├── memory/           # Memory journals (markdown, append-only)
    ├── config.yaml       # Agent-specific configuration
    └── allowlist.yaml    # Primitive permission allowlist

Key points:

• Single database: Everything is stored in moxxy.db using SQLite WAL mode. There are no separate memory.db or swarm.db files.
• Vault key: The vault.key file is created with 0600 permissions and contains the AES encryption key for secrets.
• Agent isolation: Each agent gets its own directory with a sandboxed workspace, memory journals, and allowlist.

Next Steps

Now that you have a running agent:

1. First Steps -- Learn about primitives, skills, vault, and channels
2. Core Concepts: Agents -- Understand agent lifecycle, personas, and workspaces
3. Core Concepts: Primitives -- Explore the 85 built-in primitives
4. Connect Channels -- Add Telegram or Discord integration
5. API Reference -- Full REST API documentation