Daemon and runtimes

Multica records and coordinates the work; connected computers execute it. The daemon on a computer claims runs and invokes the AI coding tools installed on that machine.

Daemon vs runtimeCopy Anchor Link

• The daemon is the Multica background process running on one computer. It connects to the server, discovers local tools, claims runs, and reports results back.
• A runtime represents one concrete execution environment available to a workspace. It corresponds to one computer plus one AI coding tool — or one custom runtime profile — on that computer.

For example, if a computer has both Claude Code and Codex installed and is connected to two workspaces, the daemon registers one Claude Code runtime and one Codex runtime for each workspace. Restarting the daemon updates the existing records; it does not keep creating new runtimes for the same combination.

Execution location and data boundariesCopy Anchor Link

The AI coding tools a local runtime invokes, those tools' own login credentials, and your local code directories all stay on the connected computer. The Multica server does not execute commands on behalf of local tools, and it does not automatically upload your entire working directory.

So the team can collaborate, the server stores issues, comments, agent configuration, run context, run records, and the results agents write back. That content can include code snippets or other project context an agent chose to read and include in its replies.

Starting the daemonCopy Anchor Link

The daemon runs in the background by default. Common commands:

To place run workspaces on another disk, persist a root for the current profile with multica config set workspaces_root <path>, or pass --workspaces-root <path> to daemon start or daemon restart. The flag overrides MULTICA_WORKSPACES_ROOT, which overrides the profile config. Existing run directories are not moved when the root changes.

On startup, the daemon detects supported AI coding tools on PATH and registers runtimes for the workspaces you are allowed to connect. If a tool was just installed or signed in, restart the daemon to detect it.

The daemon needs at least one built-in supported AI coding tool detected before it will start. Install methods and executable names are in Install AI coding tools.

Start at loginCopy Anchor Link

A daemon started from the CLI does not come back on its own after a reboot. To have it start automatically, register the current profile:

multica daemon autostart enable
multica daemon autostart status
multica daemon autostart disable

The registered command is multica daemon start --foreground for that profile, launched by the OS at login: a Run registry value for the current user on Windows, a LaunchAgent in ~/Library/LaunchAgents on macOS, and a systemd user unit on Linux, or an XDG autostart entry when no systemd user session is available. For a named profile, add --profile <name>; each profile is registered separately.

• Only enable creates the registration. multica daemon start never registers on its own; it prints a one-line hint when nothing is registered, and when a Multica-created entry exists it refreshes the executable path in it, so upgrading or moving the CLI does not require another enable.
• On macOS and Linux, the login session receives only the PATH captured from your shell at enable time. Other exported variables (API keys, HTTPS_PROXY, and so on) do not carry over. Persist daemon settings with multica config set and put other variables in your user environment.
• A systemd user unit starts at login. To start at boot without logging in, run loginctl enable-linger <username> as the enable output suggests.
• multica daemon stop stops the running daemon but keeps the registration.
• If a file Multica did not create already sits at that location (your own systemd unit, for example), enable and disable refuse to modify it.
• A daemon launched by Desktop is managed by Desktop; daemon start neither hints nor refreshes a registration for it.

Dispatch and online statusCopy Anchor Link

Once registered, a runtime keeps a persistent connection. When a new run enters the queue, the server notifies the matching daemon; the daemon also polls periodically so a dropped connection does not lose the notification. When a runtime is online with spare capacity, runs usually start immediately.

The daemon sends a heartbeat every 15 seconds. The server combines heartbeats and connection state to decide whether a runtime is online; after a daemon exits unexpectedly, the runtime is marked offline within about 3 minutes at the latest. For the first 5 minutes after losing contact, the Runtimes page shows it as "Recently lost", then as "Offline".

When a runtime is offline:

• Runs already queued wait for the runtime to recover; they do not move to another computer. A queued run fails only once the runtime has stopped heartbeating for longer than the reconnect grace and the run has itself been queued that long. A runtime that is merely busy keeps its backlog, and work assigned to an already-offline runtime still gets a full grace period to wait.
• Runs already in progress do not fail right away. They fail with runtime_offline only after the runtime's heartbeat has been missing longer than the reconnect grace (MULTICA_RUNTIME_RECONNECT_GRACE, 3 hours by default); eligible issue or chat runs can retry automatically.
• When the daemon starts again, it re-registers its runtimes and reclaims runs that did not end cleanly last time.
• A runtime offline for more than 7 days with no agents bound to it (including archived ones) is cleaned up automatically.

In the demo below, a run assigned while the computer is offline waits in the queue and is claimed only after the computer comes back online.

Detailed states and retry rules are in Runs.

Concurrency limitsCopy Anchor Link

One daemon executes at most 20 runs at a time by default; each agent at most 6. Effective concurrency is the smaller of the two.

Once a limit is reached, new runs keep queueing. Adjust a single agent's concurrency in the agent settings, and the machine-wide cap with MULTICA_DAEMON_MAX_CONCURRENT_TASKS. Parallel runs compete for machine capacity, tool account quota, and the same working directory all at once.

Token usage, cost, and failures across runs are summarized per workspace on the Analytics page; multica runtime usage <runtime-id> shows token usage for a single runtime.

Local MCP configurationCopy Anchor Link

When an agent has no MCP configuration saved, Multica passes no MCP settings and the tool reads its own configuration on that computer as usual.

Once an agent has an MCP configuration (even an empty one), Multica generates a dedicated configuration for each run and hands it to the tool; Claude Code, for example, loads only that file in strict mode. So that servers already set up on the machine keep working, the daemon reads the tool's user-level MCP configuration on the runtime's computer and merges it with the agent's. For servers with the same name, the first source in this order wins:

1. Servers managed by Multica or assigned from the workspace MCP library on the agent's MCP tab;
2. The tool's user-level configuration file;
3. Claude Code only: MCP servers bundled with enabled Claude Code plugins. Plugins come from enabledPlugins in ~/.claude/settings.json; the daemon reads each plugin's .mcp.json and any MCP files its manifest declares.

CodeBuddy, Kimi CLI, and Pi load their user-level configuration themselves at startup and combine it with what Multica sends, so the daemon does not pre-merge for them; doing so would start the same server twice. CodeBuddy keeps the Multica entry when names collide. Other tools not in the table receive only the agent's configuration.

The merge happens on the runtime's computer; the commands, URLs, headers, and environment values of local servers are never uploaded. The "Inherited from runtime" list on the agent's MCP tab shows only each server's name, transport, source, and whether it is enabled; one shadowed by a same-named agent server is marked "Overridden by Multica". If a local configuration file cannot be parsed, the daemon logs a warning and that run uses only the agent's configuration.

Cleanup and retentionCopy Anchor Link

The daemon runs its first cleanup about 30 seconds after starting, then every 2 hours. Directories in use by a running run are never cleaned. multica daemon disk-usage shows usage per workspace or per run. The durations below are defaults; the matching MULTICA_GC_* variables are in Environment variables.

Run directoriesCopy Anchor Link

Each run gets a directory under the workspaces root (default ~/multica_workspaces) holding the checked-out code, output, and logs; later runs on the same issue reuse it. The whole directory is removed:

While the issue is still open, 12 hours after a run completes only regenerable content is removed: node_modules, .next, and .turbo directories, plus the cache the daemon prepares for Codex. Everything else stays. A daemon connected to Multica Cloud also removes the whole directory 14 days after the run completes, whether or not the issue is closed; self-hosted daemons do not do this by default.

A run on a project's local directory works in your own directory, which the daemon never touches. The record directory Multica creates for that run (logs and so on) is kept too; only regenerable caches inside it are cleaned.

Shared repository cacheCopy Anchor Link

The daemon keeps one bare-repository cache per workspace repository, under .repos/<workspace-id>/ in the workspaces root. Runs of the same workspace on this computer share it: each checkout creates a git worktree from the cache and only fetches new commits instead of cloning again. Codex runs on Linux and Windows are the exception and get a standalone clone with .git inside the work directory, because Codex's workspace-write sandbox leaves Git metadata outside the work directory read-only.

A cache is removed only when all three hold: no workspace or project references the repository any more, no worktrees remain, and no run has checked out from it for 30 days. It is cloned again when needed. After removing stale agent branches, the daemon runs git reflog expire --expire=30.days --all and git gc --prune=30.days on the cache while no runs are executing.

Sessions, memory, and temporary directoriesCopy Anchor Link

Codex native memory and subagentsCopy Anchor Link

Daemon-managed Codex runs have Codex native memory turned off by default, so memories from this machine or an earlier run do not carry into another workspace. The setting is written only to that run's own CODEX_HOME/config.toml (features.memories, memories.generate_memories, and memories.use_memories all false); your ~/.codex/config.toml is not changed. To keep native memory, set MULTICA_CODEX_MEMORY=1 in the daemon's environment.

Codex native subagents are off by default as well: Multica treats the run as finished when the parent thread finishes, and results from subagents still working are lost. If you accept that risk, set MULTICA_CODEX_MULTI_AGENT=1.

Runtime sharingCopy Anchor Link

A local runtime is private by default: only the runtime owner can create agents on it, and workspace owners and admins are no exception. The runtime is someone else's computer, and running an agent there uses their machine and their tool credentials.

Only the owner can make it public. Workspace admins can rename or delete a runtime, but sharing one is the owner's decision. Once it is public, other workspace members can select this runtime and route their agents' runs to this computer; the underlying AI coding tool's login credentials are not shared.

To share it with selected people instead, open the runtime's detail page, choose Members, pick one or more workspace members, and Save. Those members can select the runtime and create agents on it. Only the owner can change the list, and being on it does not let anyone rename, delete, or administer the runtime.

When the owner removes members, narrows a public runtime to specific members, or makes it private again, Multica shows the affected agents and active runs, including Agent Builder sessions, before applying the change. Confirmation unbinds those teammates' agents, cancels their queued, dispatched, running, local-directory-waiting and deferred runs with runtime_access_revoked, and pauses active autopilots assigned to the unbound agents. Agents and runs belonging to the owner or to members who keep access are unaffected. A changed plan requires renewed confirmation; concurrent chat writes may require a retry. To resume work, bind the agent to an accessible runtime, then explicitly resume its paused autopilots.

Cancellation preserves chat history and stores draft/attachment recovery data on the server. Web and desktop use the existing draft recovery UI; mobile does not yet expose that recovery UI. A started turn with no output waits for the daemon's cancellation acknowledgement or the server's finalize grace period before deciding whether to restore the input. A connected daemon observes cancellation through its regular check. If the computer is offline, server-side access is still revoked immediately, but the local process may continue until it receives cancellation after reconnecting; the server cannot guarantee an immediate remote stop.

Custom runtime profilesCopy Anchor Link

If your team uses an internal wrapper, a version-pinned executable, or needs fixed extra arguments for a compatible tool, create a custom runtime profile.

A custom profile does not add a new communication protocol. You still pick one of the protocol families Multica already supports (the tool's integration protocol type; see AI coding tools comparison), and the command itself must be compatible with that family.

Task runtime environmentCopy Anchor Link

When the daemon starts an agent task, it injects task context into the runtime process. These values are owned by the daemon: an agent's custom environment cannot override any MULTICA_ variable or the task temporary-directory variables.

The table lists the variables that custom runtimes can use today. It is intentionally not exhaustive and is not a versioned API surface. Build integrations only on the five variables marked integration contract; treat the rest as informational details that may change.

The server determines authorship for requests made with MULTICA_TOKEN; writes such as issue comments are attributed to the assigned agent and active task. For the token's complete binding, permissions, attribution, 24-hour maximum lifetime, and cleanup behavior, see Temporary tokens for agent runs.

Creating a profileCopy Anchor Link

Only workspace owners and admins can create, edit, or delete custom runtime profiles:

1. Open Runtimes and go to a computer where the command is installed.
2. Click Add custom runtime.
3. Choose the protocol family the command is actually compatible with.
4. Fill in the name, command, and fixed arguments, then save.

The profile is shared across the workspace. Each connected computer looks up the command on its own; only computers that can resolve it on PATH register the corresponding runtime. Creating a profile does not install the command, and it does not sign other members in to the tool.

The command field takes an executable and arguments, not a shell script. Plain arguments, quotes, and backslash escapes work; pipes, redirects, &&, ;, backticks, and environment variable expansion do not. When you need those behaviors, put them in a wrapper script and use that script as the command.

How your arguments are orderedCopy Anchor Link

Everything you type in the command field stays directly after the executable, ahead of the arguments Multica adds:

<your command> <your fixed arguments> <Multica's protocol arguments> <the agent's custom arguments>

Subcommand-style wrappers rely on this order. If your command is ccms start q36, the tool sees start q36 first and selects its subcommand before Multica's -p and the rest arrive; such a wrapper accepts no other order.

Your arguments used to be appended last. Most flag-style commands parse the same either way, but a command that distinguishes global flags from subcommand flags cares where a flag sits. If you already have a profile with fixed arguments, start one run on it after upgrading to confirm it still works.

Also:

• Multica's own values win a conflict. If your fixed arguments set a flag Multica also sets, Multica's value comes later and takes effect. Most importantly, a model chosen on the agent overrides a --model pinned in the profile. To pin a model for everyone, leave the agents' model field empty.
• Protocol-critical flags are ignored. -p, --output-format, --input-format, --permission-mode, and the equivalents for other families are dropped from your fixed arguments, because overriding them would break the daemon's connection to the tool. Subcommands and other positional arguments always pass through.

If a Desktop-launched daemon cannot find a command your terminal can run, set an absolute path for the current computer:

multica runtime profile set-path <profile-id> --path /absolute/path/to/command

Remove the path override:

multica runtime profile unset-path <profile-id>

Editing a profile only affects runs claimed afterwards. Before deleting a profile, deal with the active agents still bound to its runtimes. Deleting only the runtime instance on one computer does not delete the profile — a running daemon will re-register it.

Qoder Cloud Agents remote runtimeCopy Anchor Link

Qoder Cloud Agents runs assigned issues through remote sessions. The Multica server supervises a bridge that uses the existing daemon task protocol; no user-operated local daemon is needed for this runtime.

Before you startCopy Anchor Link

• You need to be a workspace administrator. Each workspace has one Qoder connection.
• Create a Qoder personal access token (PAT), at least one environment, and the agents you want to use in Qoder Cloud Agents. Models, tools, and skills are configured on the remote agent in Qoder Cloud Agents, not in Multica.
• Self-hosted installations must set MULTICA_VCS_SECRET_KEY on the server: a base64-encoded 32-byte key that stays the same across restarts. Without it, Qoder Cloud Agents does not appear in the Add menu.

Connect QoderCopy Anchor Link

1. On the Runtimes page, click Add and choose Qoder Cloud Agents under Cloud services.
2. Under Region, pick the site that issued your PAT: Global (qoder.com) or China (qoder.com.cn). A PAT only works in its own region; if it is rejected, use the button that retries on the other site.
3. Paste the PAT into Personal access token. Once it is verified, the Environment list loads from Qoder. A single environment is selected automatically; otherwise choose one.
4. Optional: open GitHub authorization and add a repository URL and token for each repository agents may clone. Agents can only clone repositories authorized here.
5. Optional: open Execution to set concurrent runs (default 3, up to 10) and the run timeout (default 60 minutes, from 5 to 240).
6. Click Connect. Qoder Cloud Agents appears in the cloud section of the Runtimes page and comes online within a few seconds.

Add an agentCopy Anchor Link

Open Qoder Cloud Agents from the Runtimes page and click Create an agent with it, or create an agent as usual and choose the Qoder runtime. In the agent form, select the remote agent under Remote agent. For an existing agent, change the linked agent or its default repository in the agent's Qoder Cloud Agents tab. Several Multica agents can share one connection, each linked to a different agent in Qoder Cloud Agents.

Connection credentials are encrypted and shared within the workspace. Administrators manage the connection; members can select accessible agents in Qoder Cloud Agents. Projects choose the repository and starting branch; the repository's token is passed to Qoder Cloud Agents when a coding session is created. PAT values are never returned to the browser after saving.

On the Qoder Cloud Agents page, administrators can edit the connection and repositories, Pause to stop sending new tasks while keeping credentials and agents, or Disconnect to delete the saved tokens, remove the runtime, and unbind its agents.

How runs workCopy Anchor Link

Runs beyond the concurrency limit wait in the queue. A follow-up on the same issue continues the agent's previous Qoder session when it is idle. An agent can set a default repository, used when the issue's project has none. The agent is asked to push a branch named after the issue identifier and to prefix the pull request title with it, so the pull request is linked to the issue.

This first version supports issue runs, progress reporting, cancellation, and recovery from a persisted run journal. Configure models, tools, and skills in Qoder. Interactive chat, local directories, attachments, and creating agents in Qoder Cloud Agents from Multica are not supported. The Runtimes page separates remote runtimes from connected computers.

For standalone bridge setup and operational limitations, see the Qoder runtime README.

Troubleshooting an offline runtimeCopy Anchor Link

Check in this order:

1. Run multica daemon status to confirm the daemon is running.
2. Run multica daemon logs -f to look for login, network, or tool-detection errors.
3. Run command -v <tool-command> in the same environment to confirm the daemon can find it.
4. Open Multica's Runtimes page and check whether the target computer and the matching AI coding tool show as online.
5. After a tool install, a path change, or a profile update, run multica daemon restart.

If the problem persists, see Troubleshooting.

Next stepsCopy Anchor Link

• Install AI coding tools — install and verify a supported AI coding tool.
• AI coding tools comparison — compare models, session resumption, MCP, and skill support.
• Runs — queueing, stopping, and retries.