Quick Start

Get your first Moxxy agent running in under 5 minutes.

Step 1: First-Time Setup

Run the onboarding wizard to configure Moxxy:

moxxy init

The wizard will guide you through:

1. LLM Provider Selection - Choose your AI provider
2. API Key Configuration - Enter your API key securely
3. Default Agent Creation - Set up your first agent

LLM Providers

Provider	Models	Get API Key
OpenAI	GPT-4o, GPT-4o-mini, o1, o3-mini	platform.openai.com
Google	Gemini 2.0 Flash, Gemini 2.5 Pro	aistudio.google.com
Z.Ai	Grok	x.ai

TIP

Your API keys are stored encrypted in the agent's vault. They never leave your machine.

Step 2: Start the Gateway

The gateway is the background process that runs your agents:

moxxy gateway start

You should see output like:

✓ Gateway started (PID: 12345)
✓ API listening on http://127.0.0.1:17890

Verify Gateway Status

moxxy gateway status

Step 3: Launch the Web Dashboard

Open the web interface:

moxxy web

This opens your browser to http://127.0.0.1:3001 (or the next available port).

The dashboard provides:

• Chat Interface - Talk to your agents
• Skills Manager - View and manage agent capabilities
• Memory Viewer - See what your agent remembers
• Channel Configuration - Set up Telegram, Discord, etc.
• Settings - Configure LLM providers and preferences

Step 4: Chat with Your Agent

In the web dashboard, you'll see your default agent. Try sending a message:

Hello! What can you help me with?

The agent will respond using its configured LLM and available skills.

Alternative: Terminal UI

If you prefer the command line:

moxxy tui

The terminal UI provides:

• Real-time chat with your agent
• Message history
• Slash commands for quick actions

TUI Commands

Command	Description
/help	Show available commands
/clear	Clear the chat history
/agent <name>	Switch to a different agent
/quit	Exit the TUI

Alternative: One-Shot Prompt

For programmatic use or quick tasks:

moxxy run --agent default --prompt "What is the capital of France?"

Directory Structure

After setup, Moxxy creates the following structure:

~/.moxxy/
├── agents/
│   └── default/
│       ├── persona.md      # Agent personality
│       ├── memory.db       # SQLite memory store
│       ├── current.md      # Short-term memory snapshot
│       ├── skills/         # Custom skills
│       └── container.toml  # Runtime configuration
├── run/
│   └── moxxy.pid           # Gateway PID file
└── swarm.db                # Shared knowledge base

Next Steps

Now that you have Moxxy running:

1. Understand Agents - Learn how agents work
2. Explore Skills - See what your agent can do
3. Connect Channels - Add Telegram, Discord, etc.
4. Customize Your Agent - Make it yours