Agent Management CLI

Manage your agents through the command line.

Overview

moxxy agent <subcommand> [options]

Subcommands

Command	Description
list	List all agents
restart	Restart an agent
remove	Remove an agent

List Agents

View all configured agents:

moxxy agent list

Output

┌─────────────┬──────────────┬─────────┬────────────┐
│ Name        │ Persona      │ Skills  │ Channels   │
├─────────────┼──────────────┼─────────┼────────────┤
│ default     │ Assistant    │ 12      │ Telegram   │
│ researcher  │ Research Bot │ 8       │ -          │
│ coder       │ Developer    │ 15      │ Discord    │
└─────────────┴──────────────┴─────────┴────────────┘

Restart Agent

Reload an agent's configuration without restarting the entire gateway:

moxxy agent restart <name>

When to Use

• After editing persona.md
• After adding new skills
• After modifying container.toml
• To clear memory and start fresh

Example

moxxy agent restart default

What Happens

1. Agent is marked for reload
2. Current state is saved
3. Agent is re-initialized with new configuration
4. Channels are reconnected

Remove Agent

Permanently delete an agent and all its data:

moxxy agent remove <name>

DANGER

This action is irreversible. All agent data will be deleted:

• Persona configuration
• Memory database (all conversations)
• Encrypted vault (all secrets)
• Custom skills
• Container configuration

Confirmation

You will be prompted to confirm:

$ moxxy agent remove old_agent

  ⚠ This will permanently delete agent 'old_agent' including:
    - persona.md
    - memory.db
    - vault
    - skills/

  ? Are you sure? (y/N) y

  ✓ Agent 'old_agent' removed

Skip Confirmation

moxxy agent remove <name> --yes

Creating Agents

Agents are created by setting up their directory structure:

Manual Creation

# Create agent directory
mkdir -p ~/.moxxy/agents/my-agent

# Create persona
cat > ~/.moxxy/agents/my-agent/persona.md << 'EOF'
You are a specialized agent for [purpose].
Your key characteristics are:
- [characteristic 1]
- [characteristic 2]
EOF

# Initialize (first prompt creates memory.db)
moxxy run --agent my-agent --prompt "Hello, introduce yourself"

Using Templates

# Copy from existing agent
cp -r ~/.moxxy/agents/default ~/.moxxy/agents/new-agent

# Edit the persona
nano ~/.moxxy/agents/new-agent/persona.md

# Clear old memory
rm ~/.moxxy/agents/new-agent/memory.db
rm ~/.moxxy/agents/new-agent/current.md

Agent Directory Structure

~/.moxxy/agents/<name>/
├── persona.md        # Agent personality and instructions
├── memory.db         # SQLite database (STM + LTM)
├── current.md        # Human-readable STM snapshot
├── container.toml    # Runtime configuration
├── skills/           # Custom skills (optional)
│   └── my_skill/
│       ├── manifest.toml
│       └── run.sh
└── vault/            # Encrypted secrets (auto-created)

persona.md

Defines the agent's personality and behavior:

# Persona

You are a helpful assistant specialized in [domain].

## Capabilities
- You can help with X, Y, Z
- You have access to [skills]

## Constraints
- Never share sensitive information
- Always verify facts before stating them

## Communication Style
- Be concise but thorough
- Use examples when explaining concepts
- Ask clarifying questions when needed

container.toml

Controls the agent's runtime environment:

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

# WASM-only settings
[runtime.wasm]
image = "base"   # "base", "networked", or "full"

[capabilities]
filesystem = ["./skills", "./memory"]
network = true
max_memory_mb = 128
env_inherit = false

Best Practices

Naming Conventions

• Use lowercase with hyphens: my-agent, research-bot
• Be descriptive: email-assistant, code-reviewer
• Avoid special characters

Persona Guidelines

1. Be specific - Generic personas give generic responses
2. Define boundaries - What should/shouldn't the agent do
3. Set tone - Professional, casual, technical, etc.
4. Include context - Domain knowledge the agent needs

Memory Management

Agents accumulate memory over time. To reset:

# Clear memory but keep persona
rm ~/.moxxy/agents/my-agent/memory.db
rm ~/.moxxy/agents/my-agent/current.md

# Restart to reinitialize
moxxy agent restart my-agent

Troubleshooting

Agent Not Appearing

1. Check directory exists:

   ls ~/.moxxy/agents/

2. Verify persona.md exists:

   cat ~/.moxxy/agents/my-agent/persona.md

3. Restart gateway:

   moxxy gateway restart

Agent Not Responding

1. Check gateway logs:

   moxxy logs | grep my-agent

2. Verify LLM configuration:

   moxxy doctor

3. Try a simple prompt:

   moxxy run --agent my-agent --prompt "Hello"

Memory Issues

If memory.db is corrupted:

# Backup first
cp ~/.moxxy/agents/my-agent/memory.db ~/backup/

# Check integrity
sqlite3 ~/.moxxy/agents/my-agent/memory.db "PRAGMA integrity_check;"

# If corrupted, reset
rm ~/.moxxy/agents/my-agent/memory.db
moxxy agent restart my-agent