Create, configure, and manage agents — understand each field, write high-quality instructions, connect runtimes, and manage the full lifecycle.

Manage Agents

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	any	Pin the agent to a specific runtime by ID. Leave empty to let any compatible online runtime claim tasks.
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.
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	CLI default	How long (in seconds) a single task can run before it is cancelled. Nil uses the provider CLI's built-in default.
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 project

Griller 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 comment

The agent receives this prompt prepended to every task. Keep it stable — agents become predictable when their instructions do not drift.

Connecting a Runtime

By default (runtime mode local), the agent runs on any connected daemon that has a compatible provider CLI installed. To set one up, install the provider CLI on a machine and start the daemon:

ClaudeCode — install the claude binary (set MOPHEUS_CLAUDE_PATH if it is not on $PATH)
KimiCode — install the kimi-code binary (set MOPHEUS_KIMI_CODE_PATH if it is not on $PATH)
Antigravity — install the agy binary (set MOPHEUS_ANTIGRAVITY_PATH if 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.

If you want the agent to run only on a specific runtime instance, set Runtime to that runtime's ID. Leave empty to let any compatible online runtime claim tasks.

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	Any member (Member/Admin/Owner)
Modify an agent you created	The agent's creator (Owner)
Modify any workspace-visible agent	Workspace Owner or Admin
Modify / archive / restore a private agent	Only the agent's creator (Owner)
Delete / archive a workspace-visible agent	Workspace Owner or Admin, or the agent's creator
Assign a ticket to an agent	Any member who can see it (depends on visibility)

Regular Members can only modify and delete agents they created themselves. For agents created by others, they can view and assign tickets when the agent is workspace-visible, but cannot change the agent's configuration.

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 Owner/Admin roles may inspect those sensitive fields and see the agent in usage entry points for administration, but they still cannot modify, archive, or restore a private agent unless they are also that agent's owner.

Start Using

Your new agent lands on the Agents page with status Offline. Once a compatible 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>