First Steps

Now that Moxxy is running and you have your first agent, let's explore the key concepts and capabilities.

Understanding Agents

Every Moxxy agent is an isolated unit with its own:

• Workspace -- A sandboxed directory (~/.moxxy/agents/{id}/workspace/) where the agent can read and write files. OS-level sandboxing (sandbox-exec on macOS, bwrap on Linux) confines the agent to this directory.
• Persona -- A system prompt that defines the agent's personality, expertise, and behavioral constraints.
• Memory -- Append-only markdown journals for long-term memory, plus SQLite embeddings for semantic recall.
• Vault grants -- Agents must be explicitly granted access to specific secrets. No agent can access secrets it hasn't been granted.
• Allowlist -- A per-agent YAML file controlling which primitives the agent is permitted to use.

Primitives (Not "Skills")

Moxxy provides 85 built-in primitives -- atomic operations that agents can invoke during a run. These are distinct from skills (see below). Some commonly used primitives:

Category	Examples	Purpose
Filesystem	fs.read, fs.write, fs.list, fs.remove	File operations within the workspace
Git	git.clone, git.status, git.commit, git.push, git.pr_create	Repository management
Shell	shell.exec	Run shell commands (allowlist enforced)
Web	browse.fetch, browse.extract	Fetch and parse web content
HTTP	http.request	Make HTTP requests (domain-gated)
Memory	memory.store, memory.recall, memory.stm_read, memory.stm_write	Long-term and short-term memory
Vault	vault.set, vault.get, vault.delete, vault.list	Encrypted secret management
Agent	agent.spawn, agent.status, agent.list, agent.stop	Sub-agent management
Hive	hive.create, hive.recruit, hive.task_create, hive.signal	Multi-agent orchestration
MCP	mcp.connect, mcp.tool, mcp.list	External tool server integration

Primitives are gated by the agent's allowlist.yaml. You can manage the allowlist via the API or the allowlist.add / allowlist.remove primitives.

Creating Agents

Create agents via the REST API:

curl -X POST http://127.0.0.1:3000/v1/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "researcher",
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514",
    "persona": "You are a research assistant. You gather information from the web, summarize findings clearly, and cite your sources."
  }'

You can also update an existing agent's configuration:

curl -X PATCH http://127.0.0.1:3000/v1/agents/researcher \
  -H "Content-Type: application/json" \
  -d '{
    "persona": "You are a senior research analyst specializing in technology trends."
  }'

List all agents:

curl http://127.0.0.1:3000/v1/agents

Running Tasks

Start a run by sending a prompt to an agent:

curl -X POST http://127.0.0.1:3000/v1/agents/researcher/runs \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Fetch the Hacker News front page and summarize the top 5 stories."
  }'

The agent will use primitives like browse.fetch to retrieve the page, reason about the content, and produce a summary.

Example Tasks

File management:

Find all TODO comments in my workspace and create a summary file.

The agent uses shell.exec and fs.write to search and produce output.

Git operations:

Clone https://github.com/example/repo, review the recent commits, and summarize the changes.

The agent uses git.clone, git.status, fs.read, and reasoning to produce a report.

Research:

Fetch the latest release notes for Rust 1.80 and summarize the key changes.

The agent uses browse.fetch and browse.extract to get the information.

Managing Secrets

Secrets are stored in the vault with AES-GCM encryption. Agents must be explicitly granted access to specific secrets.

Store a Secret via the API

curl -X POST http://127.0.0.1:3000/v1/vault/secrets \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GITHUB_TOKEN",
    "value": "ghp_xxxxxxxxxxxx"
  }'

Grant an Agent Access

curl -X POST http://127.0.0.1:3000/v1/vault/grants \
  -H "Content-Type: application/json" \
  -d '{
    "secret_name": "GITHUB_TOKEN",
    "agent_id": "researcher"
  }'

Once granted, the agent can access the secret using the vault.get primitive during a run. Secrets are automatically redacted from all SSE events.

Connecting Channels

Channels let your agents communicate through messaging platforms. Moxxy supports Telegram and Discord.

Telegram

Using the CLI:

moxxy channel telegram

This walks you through:

1. Creating a bot via @BotFather
2. Entering the bot token
3. Pairing your Telegram user to an agent

Or via the API:

curl -X POST http://127.0.0.1:3000/v1/channels \
  -H "Content-Type: application/json" \
  -d '{
    "type": "telegram",
    "config": {
      "bot_token": "123456:ABC-DEF..."
    }
  }'

Discord

moxxy channel discord

See the Channels documentation for detailed setup guides.

Heartbeats

Heartbeats enable scheduled, autonomous agent behavior. An agent with a heartbeat wakes up on a cron schedule, executes a task, and goes back to sleep.

Create a Heartbeat via the API

curl -X POST http://127.0.0.1:3000/v1/agents/{id}/heartbeats \
  -H "Content-Type: application/json" \
  -d '{
    "cron": "0 9 * * *",
    "prompt": "Check the status of my production server at https://example.com/health and notify me on Telegram if it is down."
  }'

This creates a heartbeat that fires every day at 9:00 AM. The agent will use http.request to check the server and channel.notify to send alerts.

List heartbeats:

curl http://127.0.0.1:3000/v1/agents/{id}/heartbeats

Skills

Skills are distinct from primitives. While primitives are atomic built-in operations, skills are reusable procedures defined as Markdown files with YAML frontmatter:

---
id: summarize-url
name: Summarize URL
version: 1.0.0
inputs_schema:
  type: object
  properties:
    url:
      type: string
      description: The URL to summarize
  required: [url]
allowed_primitives:
  - browse.fetch
  - browse.extract
  - memory.store
safety_notes: |
  Only fetches the provided URL. Does not follow external links.
---

# Summarize URL

Fetch the content at the given URL and produce a concise summary.

## Steps

1. Use `browse.fetch` to retrieve the page content
2. Use `browse.extract` to pull the main text
3. Summarize the content in 3-5 bullet points
4. Store the summary in memory with `memory.store`

Key points about skills:

• All skills start quarantined and require explicit approval before an agent can use them
• Skills declare which primitives they are allowed to use
• Moxxy ships with 9 example skills
• Install skills via the API: POST /v1/agents/{id}/skills/install

Best Practices

1. Use Specific Personas

Generic personas lead to generic responses. Be specific about expertise areas, communication style, and constraints:

You are a DevOps engineer specializing in Kubernetes and AWS.
You write concise, actionable responses.
You always verify commands before suggesting them.
When unsure, you say so rather than guessing.

2. Configure Allowlists

Don't give every agent access to every primitive. A research agent probably doesn't need shell.exec or git.push. Restrict the allowlist to the minimum set of primitives needed.

3. Use Vault Grants

Never put secrets in agent personas or prompts. Store them in the vault and grant access only to the agents that need them.

4. Leverage Heartbeats for Automation

Instead of running one-off tasks, set up heartbeats for recurring work: monitoring, report generation, data collection.

Next Steps

• Core Concepts: Primitives -- Full reference for all 85 primitives
• Core Concepts: Memory -- How the memory system works
• Core Concepts: Hive -- Multi-agent orchestration with Queen/Worker hierarchy
• API Reference -- Complete REST API documentation
• Configuration: Vault -- Deep dive into secret management