Manage Agents
Create, configure, and manage agents — understand each field, write high-quality instructions, connect runtimes, and manage the full lifecycle.
Create an Agent
Open Agents in the sidebar and click New agent. The form is short, but a few of its fields deserve thought before you save.
Required Fields
| Field | Description |
|---|---|
| Name | Free-form display name. Shows up in the assignee picker, the agent list, and every comment the agent posts. Pick something role-based — DB Guardian reads better than Agent 17. |
Optional Fields
| Field | Default | Description |
|---|---|---|
| Description | empty | A short human-readable summary of the agent's purpose. Shown in the agent list. |
| Instructions | empty | The system prompt that defines the agent's persona, scope, and rules. This is the most important field — see the example below. Markdown is supported. |
| Runtime mode | local | local — tasks run on a daemon process installed on a machine; cloud — tasks run on a hosted cloud runtime (when available). |
| Runtime | none | Assign a runtime directly. The form allows this field to be empty, but an unbound agent cannot execute tasks. For ticket and comment triggers, no task is created and a system comment explains the missing binding. |
| Visibility | Workspace | Workspace agents can be selected by members with agent execution access. Private agents keep their name visible for references, hide sensitive configuration from most non-owners, and can only be modified by the agent owner or workspace Owner. |
| Griller | off | Enable this agent as a Griller reviewer. When enabled, this agent appears in the comment "Grill" dropdown menu to perform focused self-reflective reviews (grill-me). |
| Max concurrent tasks | 6 | How many tasks this agent can run at the same time. |
| Timeout | unset | A set value is used by both daemon and server. When unset, the daemon uses MOPHEUS_AGENT_TIMEOUT (default 0, no daemon deadline) and the server uses agent_task_timeout (default 24h safety sweep). |
| Environment variables | empty | Key-value pairs injected into the agent's environment when it runs. Use for API keys, regions, feature flags. Stored encrypted at rest. |
| Runtime config | empty | Provider-specific key-value configuration delivered to the runtime at task dispatch time. |
| Skills | none | Reusable capabilities defined in Skills. Pick from the workspace skill library. |
| Avatar | auto | Visual identity for the assignee picker and comment thread. |
Example Instructions
A good instructions block is specific about scope, output format, and what the agent should not do.
You are the DB Guardian, an experienced and cautious database expert.
When given a ticket:
1. Fully understand the requirement — if necessary context is missing, post a comment asking for it and stop
2. Provide professional analysis, a feasible plan, and any necessary risk warnings based on the ticket content
3. Write all conclusions as a ticket comment, keeping it professional and concise
Constraints:
- For destructive operations (such as deleting data, changing core parameters, or restarting instances), you must explicitly flag the risk in the comment and wait for human confirmation before proceeding
- Do not change the ticket's labels, assignee, or projectGriller Reviewer Example Instructions
When creating an agent specifically as a Griller reviewer (with Griller enabled), focus its instructions on domain-specific scrutiny and decision-tree exploration:
You are a rigorous Architecture Griller specializing in backend and distributed systems.
When performing a Grill Me self-reflective review on a discussion thread:
1. Focus on hidden assumptions, boundary conditions, single points of failure, concurrency hazards, and data consistency risks
2. Follow a structured self-Q&A decision-tree exploration, relentless in identifying flaws while providing recommended answers for every question
3. Output your final findings in the same primary language as the triggering discussion thread, and post them as a reply to the triggering commentThe agent receives this prompt prepended to every task. Keep it stable — agents become predictable when their instructions do not drift.
Connecting a Runtime
With runtime mode local, an agent runs on the daemon for its directly bound runtime. Install the relevant provider CLI on that machine and start the daemon:
- ClaudeCode — install the
claudebinary (setMOPHEUS_CLAUDE_PATHif it is not on$PATH) - KimiCode — install the
kimi-codebinary (setMOPHEUS_KIMI_CODE_PATHif it is not on$PATH) - Antigravity — install the
agybinary (setMOPHEUS_ANTIGRAVITY_PATHif it is not on$PATH)
Start the daemon (mopheus daemon start) and check Runtimes in the sidebar to confirm the runtime shows Online. See Install Daemon for the full setup.
Assign a runtime ID in the Runtime field before expecting the agent to execute tasks. If it is left empty, the agent can still be created or edited, but it cannot run. A ticket or comment trigger creates no task and posts a system comment; after binding a runtime, trigger the work again.
Edit an Agent
After creation, you can change instructions, description, runtime binding, concurrency limits, and more at any time. Open the agent detail page and edit in the corresponding tabs:
- Properties — change name, description, runtime binding, visibility, max concurrent tasks, timeout
- Instructions — rewrite or refine the system prompt. This is the most frequently changed field during iteration
- Skills — assign or remove skills
- Runtime Configuration — manage runtime-only settings through Environment Variables, Startup Parameters, and MCP Servers tabs. Environment variables are injected at runtime; startup parameters are passed to the provider CLI; MCP Servers accepts the agent's MCP JSON configuration.
All changes take effect immediately. Tasks already in flight are unaffected; the next assignment uses the new configuration.
Iterating on Instructions
An agent's behavior is driven directly by its instructions. Do not expect a first draft to be perfect — treat it as an ongoing refinement process:
- Assign a low-risk ticket (Backlog status, low priority)
- Read the full execution in the run record
- Adjust wording, add constraints, and tighten boundary conditions based on actual output
- Assign a similar ticket again to verify the improvement
- Repeat until the output is stable and reliable
Delete an Agent
Agents you no longer need can be archived or deleted.
- Archive — the agent is hidden from the list but all historical run records are preserved. Archived agents no longer accept new tasks, but previous runs remain viewable on the ticket timeline. Can be restored at any time.
- Delete — permanently removes the agent and its configuration. Run records remain on the tickets, but the agent itself is gone for good.
Choose Archive or Delete from the Actions menu on the agent detail page.
Permissions
Who can modify or delete an agent depends on your role in the workspace:
| Action | Who can do it |
|---|---|
| Create an agent | Member with agents:write |
| Modify / archive / delete your own workspace-visible agent | Agent owner |
| Modify another workspace-visible agent | Workspace Owner or a member with agents:write and an ownership rule that covers workspace-visible agents |
| Archive / delete another workspace-visible agent | Workspace Owner or a member with agents:manage and an ownership rule that covers workspace-visible agents |
| Modify / archive / delete a private agent | Agent owner or workspace Owner |
| Transfer agent ownership | Agent owner or workspace Owner |
| Assign a ticket to an agent | Any member who can see it (depends on visibility) |
For workspace-visible agents, the Agent owner can edit and manage their own agent. Other members need agents:write to edit or agents:manage to archive or delete, with a role ownership rule that covers workspace-visible agents. Private agents can only be edited or managed by their owner or the workspace Owner.
Private agent names are intentionally visible so existing ticket assignees, comments, and mentions remain understandable. Sensitive fields such as instructions, runtime binding, runtime configuration, environment variables, MCP configuration, custom arguments, and runtime tags are hidden from most non-owners. Workspace Owners and Admins may inspect those fields; the workspace Owner can also edit, manage, or transfer the agent, while an Admin cannot mutate it unless they are also its owner.
Start Using
Your new agent lands on the Agents page with status Offline. Once its directly bound runtime is online, the status flips to Idle.
To put it to work:
- Open any ticket
- Open the Assignee picker
- Switch to the Agents tab
- Pick the agent
The platform queues an agent task immediately. Watch progress live in the ticket's Runs tab.
Tip — start by assigning a low-risk ticket (Backlog status, low priority) so you can validate the agent's behavior before letting it loose on urgent work. Read the first few runs end-to-end; tweak the instructions until the output looks right.
Command-line Reference
# List agents in the workspace
mopheus agent list
# View agent details
mopheus agent get <agent-id>
# Create an agent (optionally flag as a dedicated Griller reviewer with --is-griller)
mopheus agent create --name "DB Guardian" --runtime-id <runtime-id> \
--instructions "You are a database diagnosis expert..." --is-griller
# Update an agent (modify properties or toggle --is-griller=true/false)
mopheus agent update <agent-id> --name "New Name" --is-griller=true
# Archive / restore (there is no `agent delete` CLI; use the web UI Actions menu to delete)
mopheus agent archive <agent-id>
mopheus agent restore <agent-id>
# Skill management
mopheus agent skills list <agent-id>
mopheus agent skills add <agent-id> --skill-id <skill-id>
mopheus agent skills remove <agent-id> <skill-id>
mopheus agent skills set <agent-id> --skill-ids <id1>,<id2> # replace all skills at once
# Avatar
mopheus agent avatar <agent-id> --file ./avatar.png
# Environment variables
mopheus agent env get <agent-id>
mopheus agent env set <agent-id> --env '{"API_KEY":"sk-..."}'
# Agent tasks
mopheus agent-task list --agent-id <agent-id>
mopheus agent-task get <task-id>
mopheus agent-task messages <task-id>
mopheus agent-task usage <task-id>
mopheus agent-task cancel <task-id>