Agent Management

Agents in Moxxy are managed primarily through the REST API. The gateway exposes endpoints for creating, listing, updating, and deleting agents.

API Endpoints

Method	Endpoint	Description
POST	/v1/agents	Create a new agent
GET	/v1/agents	List all agents
GET	/v1/agents/{name}	Get agent details
PATCH	/v1/agents/{name}	Update an agent
DELETE	/v1/agents/{name}	Delete an agent
POST	/v1/agents/{name}/runs	Start a run (send a prompt)
POST	/v1/agents/{name}/stop	Stop a running agent
POST	/v1/agents/{name}/reset	Reset agent session

All endpoints require a bearer token with appropriate scopes. See Gateway for authentication details.

Create an Agent

curl -X POST http://127.0.0.1:3000/v1/agents \
  -H "Authorization: Bearer mox_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "researcher",
    "persona": "You are a research assistant specialized in finding and summarizing information from the web.",
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514"
  }'

List Agents

curl http://127.0.0.1:3000/v1/agents \
  -H "Authorization: Bearer mox_your_token"

Get Agent Details

curl http://127.0.0.1:3000/v1/agents/researcher \
  -H "Authorization: Bearer mox_your_token"

Update an Agent

curl -X PATCH http://127.0.0.1:3000/v1/agents/researcher \
  -H "Authorization: Bearer mox_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "persona": "You are an expert research assistant with deep knowledge of academic literature."
  }'

Delete an Agent

curl -X DELETE http://127.0.0.1:3000/v1/agents/researcher \
  -H "Authorization: Bearer mox_your_token"

WARNING

Deleting an agent removes its workspace directory and all associated data. This action is irreversible.

Start a Run

Send a prompt to an agent and start execution:

curl -X POST http://127.0.0.1:3000/v1/agents/researcher/runs \
  -H "Authorization: Bearer mox_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Find the latest research papers on transformer architectures"
  }'

The response includes a run_id that can be used to track progress via SSE events.

Stop an Agent

curl -X POST http://127.0.0.1:3000/v1/agents/researcher/stop \
  -H "Authorization: Bearer mox_your_token"

Reset Agent Session

Clear the agent's current session and short-term memory:

curl -X POST http://127.0.0.1:3000/v1/agents/researcher/reset \
  -H "Authorization: Bearer mox_your_token"

Agent Directory Structure

Each agent has a directory under ~/.moxxy/agents/{id}/:

~/.moxxy/agents/{id}/
  workspace/       # Sandboxed working directory (PathPolicy confined)
  memory/          # Markdown journals (append-only)
  config.yaml      # Agent configuration (persona, model, provider)
  allowlist.yaml   # Primitive allowlist and denylist

config.yaml

Contains the agent's configuration including persona, provider, and model settings.

allowlist.yaml

Controls which primitives the agent can invoke. By default, agents have access to all 85 built-in primitives, but this can be restricted:

allowed:
  - fs.read
  - fs.write
  - shell.exec
  - git.*
denied:
  - vault.delete

workspace/

The sandboxed directory where the agent performs file operations. PathPolicy enforcement ensures the agent cannot access files outside this directory.

memory/

Contains append-only Markdown journals that record the agent's interactions and learnings. These are indexed in the central moxxy.db database with vector embeddings for semantic search.

Agent Status

Agents have one of the following statuses:

Status	Description
created	Agent exists but has not been run
running	Agent is actively processing a run
stopped	Agent was explicitly stopped
error	Agent encountered an error during execution

Best Practices

Naming Conventions

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

Persona Design

1. Be specific - Detailed personas produce better results
2. Define boundaries - What the agent should and should not do
3. Set context - Domain knowledge and expertise areas
4. Guide tone - Communication style (professional, casual, technical)

Allowlist Management

Follow the principle of least privilege. Only enable the primitives an agent actually needs:

# A research agent only needs web and memory access
allowed:
  - browse.fetch
  - browse.extract
  - memory.store
  - memory.recall
  - memory.stm_read
  - memory.stm_write
  - user.ask
  - reply