First Steps

Now that Moxxy is running, let's explore what you can do with it.

Understanding Your Agent

Your default agent comes with a set of built-in skills and a default persona. Let's explore:

View Available Skills

In the web dashboard, click the Skills tab, or run:

moxxy run --agent default --prompt "List all your available skills"

You'll see skills like:

• host_shell - Execute shell commands
• host_python - Run Python scripts
• web_crawler - Fetch web content
• git - Git operations
• scheduler - Schedule recurring tasks

View Agent Memory

Your agent maintains both short-term and long-term memory:

# In your terminal
cat ~/.moxxy/agents/default/current.md

This file contains the agent's current context and recent interactions.

Customizing Your Agent

Change the Persona

The persona defines your agent's personality and behavior:

# Edit the persona file
nano ~/.moxxy/agents/default/persona.md

Example personas:

Helpful Assistant:

You are a helpful, friendly AI assistant.
You are patient and thorough in your explanations.
You prefer to give concrete examples when explaining concepts.

Code Expert:

You are an expert software developer.
You write clean, well-documented code.
You follow best practices and design patterns.
When suggesting solutions, you explain the reasoning behind your choices.

Data Analyst:

You are a data analysis expert.
You are skilled at interpreting data and finding patterns.
You communicate insights clearly with visualizations when helpful.
You ask clarifying questions to understand the context of analysis tasks.

After editing, the changes take effect immediately for new conversations.

Configure Runtime Settings

Edit ~/.moxxy/agents/default/container.toml to control runtime behavior:

[runtime]
type = "native"    # "native" or "wasm"

[capabilities]
# These apply to WASM mode only
filesystem = ["./skills", "./memory"]
network = true

Running Tasks

Execute Shell Commands

Ask your agent to run commands:

List all files in my Downloads folder that are larger than 100MB

The agent will use the host_shell skill to execute find or du commands.

Fetch Web Content

What are the latest headlines from Hacker News?

The agent uses web_crawler to fetch and parse the content.

Schedule Tasks

Every morning at 9am, check the weather and send me a Telegram message

The agent uses the scheduler skill to create a cron job.

Creating Additional Agents

You can have multiple agents with different purposes:

# Create a new agent directory
mkdir -p ~/.moxxy/agents/researcher

# Create a persona
cat > ~/.moxxy/agents/researcher/persona.md << 'EOF'
You are a research assistant specialized in gathering and summarizing information.
You are thorough and cite your sources.
EOF

# Initialize the agent's memory
moxxy run --agent researcher --prompt "Hello, introduce yourself"

Switch Between Agents

In the TUI:

/agent researcher

Via CLI:

moxxy run --agent researcher --prompt "Your prompt here"

Managing Secrets

Store sensitive information in the encrypted vault:

Via Web Dashboard

1. Go to Config → Vault
2. Add a new secret with a key and value
3. Access it in skills via vault.get("key_name")

Via CLI

moxxy run --agent default --prompt "Store my API key xyz123 in the vault as MY_API_KEY"

Connecting Channels

Make your agent accessible from messaging platforms:

Telegram

moxxy channel telegram --agent default

Follow the prompts to:

1. Create a bot via @BotFather
2. Enter the bot token
3. Pair your Telegram account

Discord, Slack, WhatsApp

See the Channels documentation for detailed setup guides.

Monitoring

View Logs

Follow real-time gateway logs:

moxxy logs

Check System Health

moxxy doctor

This verifies:

• Gateway is running
• Database connections are healthy
• LLM provider is configured
• Channels are connected

Best Practices

1. Use Specific Personas

Generic personas lead to generic responses. Be specific about:

• Expertise areas
• Communication style
• Constraints and preferences

2. Leverage Memory

Reference past conversations:

Remember that project we discussed yesterday?

The agent searches its long-term memory for relevant context.

3. Chain Skills

Complex tasks can use multiple skills:

Clone the repo from github.com/example/project, 
analyze the codebase structure, 
and create a summary document

4. Schedule Proactive Tasks

Let your agent work autonomously:

Every hour, check if my server is responding, 
and alert me on Telegram if it's down

Common Tasks

Code Assistance

Review this pull request and summarize the changes:
https://github.com/moxxy-ai/moxxy/pull/42

File Management

Find all TODO comments in my project and create a summary

Research

Compare the features of SQLite vs PostgreSQL for a small web application

Automation

Monitor the file /var/log/app.log for errors and notify me

Next Steps

• CLI Reference - Master all CLI commands
• Skills Reference - Learn about all built-in skills
• Create Custom Skills - Extend your agent's capabilities
• API Reference - Integrate Moxxy into your applications