Runtime Overview

A runtime is the Mopheus-side representation of a Provider CLI installed on your machine. Put more plainly: one runtime ≈ one Provider CLI instance.

For example:

• You have claude (ClaudeCode CLI) and kimi-code (KimiCode CLI) installed on your laptop
• After starting mopheus daemon start, the Mopheus UI shows two runtimes
• One called "claude" (representing your ClaudeCode), and one called "kimi-code" (representing your KimiCode)

The runtime itself is not the entity that executes tasks — the provider CLI (e.g. ClaudeCode) does the actual work. The provider CLI reads and writes files in the working directory, runs commands, queries databases, and completes the agent's specific work. The runtime is just the "identity card" of the provider CLI on the Mopheus platform, letting the server know "there is a claude/kimi-code on this machine that can run tasks."

The daemon (the mopheus daemon start process) ferries tasks from the server to the provider CLI, and ferries results back. For a detailed explanation of the daemon, see What Is the Daemon.

StatusesCopy Anchor Link

Each runtime appears as a row under Runtimes in the sidebar, with one of the following statuses:

A runtime is considered offline if its daemon stops sending heartbeats for about 90 seconds.

Activation and AccessCopy Anchor Link

Activation and access are separate controls in each workspace:

• Activation decides whether a runtime can receive work. Only the runtime owner can enable or disable it.
• Visibility decides who can bind a runtime. A workspace-visible runtime is usable by workspace members; a private runtime is usable only by its owner and members or custom roles granted access.
• Members can still inspect metadata for enabled private runtimes. The UI exposes viewerCanUse for selection controls, so an ungranted runtime is never offered as a new agent binding.
• Runtime owners and eligible runtime managers can use the Access Control tab to switch visibility and grant private runtime access to members or custom roles.
• A disabled runtime is retained in its owner's Mine list, but is not available for new bindings.
• A runtime cannot be disabled while any agent is still directly bound to it. Move those agents to another runtime or remove the bindings first.
• Re-registering the same owner, daemon, and provider preserves the runtime ID, activation state, and visibility. Another owner using the same daemon identity receives a separate runtime row.

Use the activation switch on the Runtimes page to make your runtime available, and use Access Control to decide who may bind it.

Runtime Capabilities and Metadata LayeringCopy Anchor Link

When registering with the Mopheus server, each runtime reports three decoupled layers of structured metadata:

1. Daemon Execution Config:
   • Host-wide concurrency limit (maxConcurrentAgentTasks), task execution timeouts;
   • Idle watchdog thresholds (agentIdleWatchdog) and runtime task resource guard policies (runtime_guard memory and process limits);
   • These settings represent host and workspace management policies rather than CLI protocol capabilities.
2. Daemon Build and Host Metadata:
   • Daemon binary build fingerprint (gitCommit), operating system (os), and hostname identity.
3. Provider CLI Declared Capabilities:
   • Capability matrix declared by each Provider CLI itself (e.g., sandbox mount isolation, interaction in-flight guidance, MCP management);
   • Declared capabilities indicate CLI protocol support, while actual availability depends on the host environment and configuration.

Runtime and Agent RelationshipCopy Anchor Link

An agent needs a direct runtime binding before it can execute tasks. The form allows an agent to be created without one, but it cannot run until a runtime is assigned. Ticket and comment triggers create no task and post a system comment when the binding is missing; bind a runtime, then trigger the work again. The bound runtime determines which Provider CLI executes the agent.

• An agent bound to the "claude" runtime runs through ClaudeCode; one bound to "kimi-code" runs through KimiCode.
• The runtime list shows agents directly bound to each runtime; unbound agents do not appear under a runtime.
• If an agent's directly bound runtime is offline or disabled, it cannot execute new tasks on that runtime. If a fallback is configured, queued work can be redistributed according to that fallback configuration.

You can change an agent's bound runtime from the agent settings page.

Mid-Run Agent SteeringCopy Anchor Link

Providers that declare the interaction capability, such as ClaudeCode, allow an active Agent task to receive steering from the ticket detail page or chat session. This is a runtime capability; the daemon delivers it to the existing provider process and session.

• In-flight course correction: Guidance is delivered without restarting the task.
• Delivery status: Messages move through accepted -> queued -> delivering -> delivered or rejected.
• Safe withdrawal: A message can be withdrawn while it is accepted or queued; it is then never delivered.
• Realtime synchronisation: The queue and delivery status are synchronised through WebSocket events.

Workspace Registration and VisibilityCopy Anchor Link

When a daemon registers runtimes through mopheus login, each runtime record is associated with the authenticated user as its Owner.

The runtime list normally includes all enabled runtimes in the workspace, regardless of owner or visibility. Visibility controls who may bind a runtime, not who can see its basic metadata: workspace-visible runtimes can be used by members, while private runtimes can be used by their owner or members/custom roles explicitly granted access. Disabled runtimes remain only in their owner's Mine view. The ?scope=mine filter returns only the current user's runtimes. Only a runtime's owner can enable or disable it. See Activation and Access for binding eligibility.

Connection FlowCopy Anchor Link

Turning a provider CLI on your machine into a Mopheus runtime takes three steps:

1. Install the CLI and log in. Download the mopheus binary and run mopheus login to authenticate (see Install Daemon).
2. Install a provider CLI. Install claude, kimi-code, or another supported CLI on your machine, and make sure it is executable on $PATH (see Provider CLI).
3. Start the daemon. Run mopheus daemon start. The daemon automatically scans for installed provider CLIs, registers them with Mopheus, and your runtimes appear in the sidebar.

Within a few seconds, each provider CLI on your machine will have a corresponding runtime row in the UI.

One Machine, Multiple RuntimesCopy Anchor Link

A single physical machine can have multiple runtimes — as long as it has multiple provider CLIs installed.

These runtimes are backed by the same daemon. In the sidebar, each machine is grouped by runtime owner and Daemon ID, so two owners never share one management group.

Multi-Workspace and Multi-MachineCopy Anchor Link

Multi-workspace: A single daemon can connect to multiple workspaces at the same time. It registers one runtime per provider CLI in each workspace. On first registration, runtimes are enabled and workspace-visible for a workspace Owner; runtimes registered by other members start disabled and private. Activation and visibility remain independent per workspace, and re-registration preserves their manually configured values. For example, a machine with 2 provider CLIs connected to 2 workspaces has 4 runtime rows owned by you — but there is still only 1 daemon process running in the background.

Multi-machine: You can run the daemon on as many machines as you like — laptops, on-call workstations, VMs, Kubernetes pods. Each machine independently discovers its provider CLIs and registers runtimes. Agent tasks are dispatched to the machine where the bound runtime lives.

Concurrency ControlCopy Anchor Link

The concurrent task limit is controlled by the daemon, via --max-concurrent-tasks (default 20). This means: the total number of concurrent tasks across all runtimes on one machine cannot exceed this limit. For example, if your machine has both a claude and a kimi-code runtime, the tasks they run simultaneously cannot add up to more than 20.

Runtime Resource GuardCopy Anchor Link

Resource limits, configuration precedence, and guard diagnostics are documented in Runtime Resource Guard.

Command-Line ReferenceCopy Anchor Link

Common CLI commands for runtime discovery, usage analytics, and resource guards:

# === Runtime List and Status ===
mopheus runtime list                        # List all runtimes, bound agents, and online status in workspace

# === Usage and Activity Analytics ===
mopheus runtime usage <runtime-id>          # Get task usage statistics for a runtime (--days filter supported)
mopheus runtime activity <runtime-id>       # Get hourly task activity trends for a runtime