# Multica — full corpus # LLM Wiki An open-source template for building LLM-powered knowledge bases, following [Andrej Karpathy's "LLM Wiki" pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). You provide raw sources. The LLM reads them, writes structured wiki pages, cross-links everything, and maintains it over time. You never edit the wiki directly — you curate sources and ask questions. ## How It Works The system has three layers: ``` raw/ Sources you collect (articles, transcripts, notes, PDFs) wiki/ LLM-written & maintained pages (summaries, concepts, entities, syntheses) CLAUDE.md Schema that tells the LLM how to structure everything ``` Three operations drive the workflow: | Operation | Trigger | What happens | |-----------|---------|--------------| | **Ingest** | "ingest raw/my-source.txt" | LLM reads the source, creates a summary page, creates/updates concept and entity pages, adds cross-links, updates the index and log | | **Query** | Ask any question | LLM searches the wiki, synthesizes an answer with citations, optionally creates a synthesis page for novel insights | | **Lint** | "lint" or "health check" | LLM audits all pages for orphans, contradictions, missing links, incomplete sections, and low-confidence claims — fixes what it can, reports the rest | ## Quick Start 1. **Clone this repo** ```bash git clone https://github.com/YOUR_USERNAME/llm-wiki.git my-knowledge-base cd my-knowledge-base ``` 2. **Customize CLAUDE.md** for your domain - Update the Purpose section with your topic - Replace the placeholder tagging taxonomy with your own categories - Adjust confidence level descriptions if needed - Everything else (workflows, page formats, linking rules) works as-is 3. **Drop sources into `raw/`** - Text files, transcripts, articles, notes — any plain text - These are immutable once added; the LLM never modifies them 4. **Tell the LLM to ingest** ``` ingest raw/my-first-source.txt ``` The LLM will create summary pages, concept pages, entity pages, cross-links, and update the index. 5. **Ask questions** ``` What are the key differences between X and Y? ``` The LLM answers from the wiki, citing specific pages. 6. **Run health checks** ``` lint ``` The LLM audits the wiki and fixes issues. ## Directory Structure ``` . ├── CLAUDE.md # Schema — the LLM's instructions ├── raw/ # Your source documents (immutable) └── wiki/ ├── index.md # Master catalog of all pages ├── log.md # Append-only activity log ├── dashboard.md # Dataview dashboard (Obsidian) ├── analytics.md # Charts View analytics (Obsidian) ├── flashcards.md # Spaced repetition cards ├── summaries/ # One page per source document ├── concepts/ # Concept and framework pages ├── entities/ # People, tools, organizations, etc. ├── syntheses/ # Cross-cutting analyses and comparisons ├── journal/ # Research/session journal entries │ └── template.md # Journal entry template └── presentations/ # Marp slide decks ``` ## Enhancements This template includes several extras beyond the core wiki pattern: ### Dataview Dashboard (`wiki/dashboard.md`) Live queries that surface low-confidence pages, recent updates, concepts by tag, and pages with the most sources. Requires the [Dataview](https://github.com/blacksmithgu/obsidian-dataview) Obsidian plugin. ### Charts View Analytics (`wiki/analytics.md`) Visual analytics with pie charts, bar charts, and word clouds. Requires the [Charts View](https://github.com/caronchen/obsidian-chartsview-plugin) Obsidian plugin. ### Mermaid Diagrams Use Mermaid code blocks in any wiki page to create flowcharts, sequence diagrams, or concept maps. Native support in Obsidian and GitHub. ### Marp Slides (`wiki/presentations/`) Create slide decks from markdown using [Marp](https://marp.app/). Drop presentation files in this directory. ### Research Journal (`wiki/journal/`) Track your research sessions, experiments, or applied work with the included template. The LLM can reference journal entries when answering queries. ### Spaced Repetition (`wiki/flashcards.md`) Flashcards in the format used by the [Spaced Repetition](https://github.com/st3v3nmw/obsidian-spaced-repetition) Obsidian plugin. Ask the LLM to generate flashcards from any wiki page. ### MCP Server This repo works with Claude Code's MCP server capabilities. Point an MCP-compatible client at this repo and the LLM can read/write the wiki programmatically. ## Customizing for Your Domain The schema in `CLAUDE.md` is domain-agnostic. To adapt it: 1. **Purpose** — Describe your knowledge domain in one paragraph 2. **Tagging taxonomy** — Replace placeholder categories with your own (e.g., for a cooking KB: `cuisine`, `technique`, `ingredient`, `equipment`) 3. **Confidence levels** — Adjust the descriptions to match your domain's evidence standards 4. **Entity types** — Update the entity page description to match what entities mean in your domain (people, tools, companies, etc.) 5. **Journal template** — Customize `wiki/journal/template.md` for your workflow Everything else — page format, linking conventions, workflows, rules — is universal and works across domains. ## Example Domains This template works for any knowledge-intensive topic: - **Research notes** — papers, experiments, methodologies - **Book analysis** — themes, characters, author techniques - **Competitive analysis** — companies, products, market trends - **Course notes** — lectures, readings, key concepts - **Personal development** — frameworks, habits, book summaries - **Technical documentation** — APIs, architectures, design patterns - **Hobby deep-dives** — any subject you want to master ## License MIT # Multica Knowledge Base An LLM-maintained knowledge base on **Multica** (github.com/multica-ai/multica, multica.ai) — an open-source, self-hostable workspace where you assign issues to AI coding agents like teammates: they show up on a board, pick up issues, report progress, raise blockers, and hand back for review. Works with ~20 agent CLIs. Written in Go. Pinned to v0.4.22. ## Concepts - [[concepts/multica-overview|Multica Overview]] - [[concepts/core-concepts|Core Concepts]] - [[concepts/getting-started|Getting Started]] - [[concepts/board-and-work-items|Board and Work Items]] - [[concepts/assigning-issues|Assigning Issues]] - [[concepts/agents|Agents]] - [[concepts/creating-agents|Creating and Configuring an Agent]] - [[concepts/providers-and-runtimes|Providers and Runtimes]] - [[concepts/triggering-and-mentioning-agents|Triggering and Mentioning Agents]] - [[concepts/squads|Squads]] - [[concepts/autopilots|Autopilots]] - [[concepts/skills|Skills]] - [[concepts/communication|Communication]] - [[concepts/chat-integrations|Chat Integrations]] - [[concepts/vcs-integration|VCS Integration]] - [[concepts/cli-and-daemon|CLI and Daemon]] - [[concepts/desktop-and-mobile-apps|Desktop and Mobile Apps]] - [[concepts/auth-and-tokens|Authentication and Tokens]] - [[concepts/members-and-roles|Members and Roles]] - [[concepts/security-model|Security Model]] - [[concepts/configuration|Configuration]] - [[concepts/self-hosting|Self-Hosting]] - [[concepts/troubleshooting|Troubleshooting]] ## Agent Providers - [[entities/supported-agents-catalog|Supported Agents Catalog]] ## Summaries - [[summaries/release-digest|Release Digest: v0.3.37 – v0.4.22]] --- title: "Agents" type: concept tags: [agents, board, workflow, foundational, user] multica_version: "v0.4.22" created: 2026-08-10 updated: 2026-08-10 sources: ["raw/github_doc-apps-docs-content-docs-agents-mdx.md"] confidence: high --- ## Definition An **agent** is a collaborator in a Multica workspace: a reusable identity, set of capabilities, and execution configuration that you can assign issues to, @-mention in comments, or chat with directly. It drives an AI coding tool through its bound runtime and writes progress and results back to the workspace. Crucially, an agent is *not* a continuously running process — it is a reusable configuration that only produces concrete tasks when work actually arrives. ## How It Works An agent's configuration has several parts, all editable after creation without losing history: | Setting | What it does | |---|---| | Name, avatar, and description | Identify the agent to the team; the description is display-only and never enters the execution prompt. | | Instructions | Define responsibilities, working style, boundaries, and delivery requirements; used on every run. | | Skills | Reusable methods, reference material, and supporting files. | | Runtime, model, and thinking level | Which runtime, AI coding tool, and model it runs on; some tools (e.g. Codex) also offer a service tier. | | Access | Which members can run it. | | Execution settings | Concurrency limit, environment variables, CLI arguments, MCP, and external integrations. | Switching models or editing instructions does not create a new agent — past issues, comments, and task history persist. Three related concepts divide responsibility cleanly: | Concept | Responsibility | |---|---| | Agent | Decides who does the work and how | | Runtime | Decides which computer and which AI coding tool executes it | | Task | Records the process and result of one run | One runtime can host multiple agents, and one agent can complete many tasks over time. If the runtime goes offline, the agent's identity and history remain — new tasks simply wait for the runtime to come back. See [[concepts/providers-and-runtimes]] for the runtime layer. **Lifecycle on the board.** An agent participates in several ways: - **Own an issue** — set as assignee; the run starts once the task is enqueued (the issue must be in `todo` or later). - **Handle a comment** — get @-mentioned without changing the issue's assignee. - **Continue a discussion** — replying to the agent's own comment feeds new information into subsequent runs. - **Chat directly** — a conversation not attached to any issue. - **Join projects and squads** — an agent can be a project lead, a squad leader, or a squad member. - **Run through automations** — scheduled or event-triggered, or run manually. Once working, agents report back the same way a teammate would: they can create issues, post comments, and change work status. They have no inbox, however, and do not receive `@all` — an @-mention of an agent is an *execution trigger*, not a notification (see [[concepts/triggering-and-mentioning-agents]]). **Status while working.** The agent list shows two independent signals side by side: - **Availability** — comes from the runtime: online, offline, or unstable. - **Workload** — comes from tasks: working, queued, or idle. "Offline" only means the runtime is unreachable; already-enqueued tasks wait for it. Only "archived" means the agent can no longer take new work. **Archive and restore.** An agent no longer in use can be archived: it disappears from pickers and can no longer be assigned or @-mentioned, but its history is preserved and it can be restored later. Archiving cancels all of the agent's unfinished tasks, including queued and running ones. The agent owner and workspace `owner`s/`admin`s can archive or restore. ## Key Parameters - **Access** — `Only me` (default for new agents), `Entire workspace`, or `Specific people`. Only the agent owner can change Access, even workspace admins cannot bypass it to run someone else's "Only me" agent. - **Ownership** — every agent has exactly one owner. - **Concurrency limit** — part of execution settings; bounds how many tasks the agent runs at once (see [[concepts/creating-agents]] for the default value and interaction with the daemon-wide cap). - **Runtime binding** — which computer + AI coding tool combination executes the agent's tasks. ## When To Use - Assign an agent an issue when it should own a piece of work end to end. - @-mention it in a comment when you want it to weigh in without becoming the assignee. - Use direct chat for a question or quick attempt that isn't tied to an issue. - Put an agent on a squad when you want a leader to route work to whichever member fits. - Use automations/autopilots for recurring work that should not need a human to remember to trigger it. ## Risks & Pitfalls - Configuration that may contain credentials (environment variables, MCP) has stricter read rules than the rest of the agent record — see [[concepts/creating-agents]]#environment-variables-and-credentials. - New agents default to `Only me` — a newly created agent is invisible/unusable to teammates until Access is widened. - Archiving an agent cancels its unfinished tasks, including ones already running — archive deliberately, not as a quick pause. - Agents cannot bypass another agent's Access from workspace admin rights, and admins cannot run agents they weren't granted. - Because agents have no inbox and don't receive `@all`, teams sometimes assume an `@all` will loop an agent in — it will not; see [[concepts/triggering-and-mentioning-agents]]. ## Related Concepts - [[concepts/creating-agents]] — how an agent's configuration above is actually set up. - [[concepts/providers-and-runtimes]] — the runtimes that give an agent somewhere to execute. - [[concepts/triggering-and-mentioning-agents]] — the explicit actions that turn this reusable identity into a running task. - [[entities/supported-agents-catalog]] — the AI coding tool CLIs an agent can be bound to. - [[concepts/squads]] (planned) — agents as project leads, squad leaders, or squad members. - [[concepts/skills]] (planned) — reusable methods and material bound to an agent. - [[concepts/board-and-work-items]] (planned) — where an agent's issue ownership plays out. - [[concepts/security-model]] (planned) — what an agent can and can't reach. ## Sources - raw/github_doc-apps-docs-content-docs-agents-mdx.md --- title: "Assigning Issues" type: concept tags: [workflow, agents, foundational, user, well-established] created: 2026-08-10 updated: 2026-08-10 sources: ["raw/github_doc-apps-docs-content-docs-assigning-issues-mdx.md"] confidence: high multica_version: "v0.4.22" --- ## Definition Assigning an issue is Multica's core hand-off workflow: it puts an agent (or squad) in charge of a piece of work over time. The agent reads the issue's description and discussion, works with its own configuration and skills, and writes progress and results back to the same issue. Assignment is for ownership; a one-off request that shouldn't change ownership belongs in an [@-mention](/mentioning-agents) instead (raw/github_doc-apps-docs-content-docs-assigning-issues-mdx.md). ## How It Works **Assign and start a run:** 1. Open an issue and click **Assignee**. 2. Pick an agent or a squad. 3. Review the agent about to start in the confirmation dialog. 4. Add a handoff note if needed, then choose **Start**. The handoff note applies only to this run — scope, ordering, or what to focus on this time; anything that should hold long term belongs in the issue itself, the project description, or the agent's own instructions. Assigning to a [[concepts/squads|squad]] makes the squad the issue's assignee, and the squad leader starts first, deciding whether to hand work to other members. **Execution after assignment**: Multica creates a task for the agent; once an online runtime claims it, the runtime invokes the configured AI coding tool, and progress, comments, and results appear in the issue. If the runtime is temporarily offline, the task waits in the queue — a task is bound to its runtime and never moves to another machine. While executing, the agent can read the issue's description, fields, and comments; use its bound skills, MCP servers, and project context; read files, run commands, and make changes in its local working directory; and post comments and update the issue status — but what it can actually do is still bounded by the agent's own configuration, the runtime environment, and the caller's permission to run it. During the run, the agent is expected to manage status by convention: typically `todo` → `in_progress`, then `in_review` on delivery — these transitions appear under the agent's own identity in the timeline. Task lifecycle and issue status are separate: a task completing does not by itself change the issue's status. When the assignee is a squad, the same expectations apply to the leader: it moves the parent issue to `in_progress` on the first turn and keeps it there while members work, moving it to `in_review` only once the overall goal is met — a successful first dispatch is not completion. **Assign without starting**: choosing **Don't start yet** in the confirmation dialog saves the assignee without creating a task for this run — useful to settle ownership first and start once background or dependencies are ready. `backlog` status behaves the same way: it doesn't start a run on assignment either; execution follows only after the issue moves out of `backlog`, or the assignee is asked for something in a follow-up comment. This backlog behavior is the only status that defers execution on assignment — issues already in `done` or `cancelled` still start a run immediately when assigned or reassigned to an agent. **Change or remove the assignee**: switching to another agent starts a new run for the new assignee; picking a member only changes the assignee without invoking any AI coding tool; removing the assignee creates no task either. Changing the assignee, unassigning, or changing status does not stop a run already in progress — the corresponding task must be stopped explicitly in the execution log. **CLI**: ```bash multica issue assign MUL-42 --to "Agent name" multica issue assign MUL-42 --unassign ``` In scripts, use `--to-id ` to avoid matching the wrong object by name; look up UUIDs with `multica agent list --output json` or `multica workspace member list --output json`. ## Key Parameters **Assignment permissions** are governed by the agent's Access setting: | Access | Who can run it | |---|---| | Only me | Only the agent's owner | | Specific people | The owner and the listed members | | Entire workspace | Every workspace member | Workspace `owner`s and `admin`s can manage agents, but being able to see one does not mean being able to run it — the assignee picker disables agents the current member can't run. Assignment never bypasses an agent's Access; when assigning to a squad, it is the leader's Access that is checked (raw/github_doc-apps-docs-content-docs-assigning-issues-mdx.md). ## When To Use Use assignment when work needs an agent to own it over the course of multiple turns and status changes. Use a handoff note for one-time context about this particular run. Use **Don't start yet** or leave the issue in `backlog` when ownership should be settled ahead of execution — for example, waiting on a dependency or a scheduling decision. ## Risks & Pitfalls - Reassigning does not stop the previous run — the old task keeps executing until stopped explicitly in the execution log (raw/github_doc-apps-docs-content-docs-assigning-issues-mdx.md). - Only `backlog` defers execution on assignment; issues in `done` or `cancelled` still fire a run immediately when (re)assigned to an agent — a subtle exception worth remembering before bulk reassigning closed issues. - Being visible to a workspace member (e.g. because they are `owner`/`admin`) does not mean they can run a given agent — Access is checked independently and can silently disable the option in the assignee picker. ## Related Concepts - [[concepts/board-and-work-items]] — issue status conventions and the task/issue distinction referenced throughout. - [[concepts/squads]] — what happens when the assignee is a squad rather than a single agent. - [[concepts/multica-overview]] — the teammate model this workflow implements. - [[concepts/core-concepts]] — where assignment fits among the other trigger sources (mention, chat, autopilot). - [[concepts/getting-started]] — assigning the first issue in the quickstart and tutorial. ## Sources - raw/github_doc-apps-docs-content-docs-assigning-issues-mdx.md --- title: "Authentication and Tokens" type: concept tags: [auth, user, operator, foundational, well-established] created: 2026-08-10 updated: 2026-08-10 sources: ["raw/github_doc-apps-docs-content-docs-auth-setup-mdx.md", "raw/github_doc-apps-docs-content-docs-auth-tokens-mdx.md"] confidence: high multica_version: "v0.4.22" --- ## Definition Multica separates *how a human signs in* from *how a machine authenticates as that human*. Sign-in happens through email verification codes (with optional Google OAuth) and produces a browser session; everything else — the CLI, the daemon, scripts, and direct API calls — authenticates with a personal access token (PAT). A third, short-lived credential type is minted automatically for each agent run so that an agent never holds the user's own token (raw/github_doc-apps-docs-content-docs-auth-tokens-mdx.md). ## How It Works **Sign-in (browser).** A user enters an email address and receives a 6-digit verification code, valid for 10 minutes; once verified, the browser gets an `HttpOnly` JWT cookie named `multica_auth` that JavaScript cannot read directly. Sessions last 30 days by default, controlled by `AUTH_TOKEN_TTL` (accepts a Go duration or a positive integer of seconds), and the change only affects tokens issued after a restart of the API service — it does not extend already-issued sessions. Google OAuth can be layered on top by registering a client in the Google Cloud Console and setting `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, and `GOOGLE_REDIRECT_URI`; the redirect URI must match exactly (protocol, port, trailing slash) between Google's console and the env var (raw/github_doc-apps-docs-content-docs-auth-setup-mdx.md). **Email delivery.** Codes and invitation links are sent through Resend (`RESEND_API_KEY` + `RESEND_FROM_EMAIL`) or SMTP (`SMTP_HOST` + related vars); when `SMTP_HOST` is set it takes priority over Resend. With neither configured, the server still starts but only *writes* codes/invitations to the backend log — a line like `[DEV] Verification code for you@example.com: 123456` — which is fine for local development but not production. A fixed local testing code can be set with `MULTICA_DEV_VERIFICATION_CODE` (6 digits) when `APP_ENV=development`; it is ignored whenever `APP_ENV=production` (raw/github_doc-apps-docs-content-docs-auth-setup-mdx.md). **Signup gating.** Three variables jointly decide whether a *new* account can be created (existing users can always sign back in): `ALLOWED_EMAILS` (exact addresses), `ALLOWED_EMAIL_DOMAINS` (domains), and `ALLOW_SIGNUP` (default `true`). Evaluation order: an exact match in `ALLOWED_EMAILS` allows; else a domain match in `ALLOWED_EMAIL_DOMAINS` allows; else if `ALLOW_SIGNUP=false`, reject; if `ALLOW_SIGNUP=true` but any allowlist is configured and nothing matched, still reject; only when no allowlist is configured at all does `ALLOW_SIGNUP=true` allow through. Invitations do not bypass this: an invitee without an existing account must still satisfy the signup rules, so admins locking down signup need to add the invitee's email to `ALLOWED_EMAILS` first (raw/github_doc-apps-docs-content-docs-auth-setup-mdx.md). **Personal access tokens (PATs).** A PAT starts with the prefix `mul_` and represents the full account — every workspace and API the user can reach. Created under **Settings → API Token** with a name and an expiry (30 days / 90 days / 1 year / never; 90 days is preselected), the full value is shown exactly once. Afterward Multica retains only the hash, a short prefix for identification, the name, timestamps, and last-used time — the value itself cannot be recovered, so a lost token means revoke-and-recreate. `multica login` performs this dance automatically: it signs in through the browser, creates a 90-day PAT, and saves it to `~/.multica/config.json` (or `~/.multica/profiles//config.json` for a named profile). A PAT with an expiry auto-renews (extending back to 90 days) whenever fewer than 7 days remain; a failed renewal leaves the token untouched, and an already-expired or revoked token requires `multica login` again. On a browser-less machine, `multica login --token` lets the CLI prompt for a token created on the web instead. API calls pass the PAT as `Authorization: Bearer $MULTICA_TOKEN`, and workspace-scoped endpoints additionally need `X-Workspace-ID` (raw/github_doc-apps-docs-content-docs-auth-tokens-mdx.md). **Temporary agent-run tokens.** When the daemon claims a task, the server mints a short-lived token prefixed `mat_`, bound to that specific user, workspace, agent, and task; it is valid at most 24 hours and cleaned up when the task ends. This is what the daemon injects into the AI coding tool — never the user's own PAT — so agent actions are recorded as agent actions and the token cannot reach operations restricted to human users or owners. Two further prefixes exist for narrower internal scenarios and are never created manually by users: `mcn_` (Multica Cloud Node connections, managed by Multica Cloud Fleet) and `mdt_` (workspace-scoped daemon authentication protocol, managed by internal server flows) (raw/github_doc-apps-docs-content-docs-auth-tokens-mdx.md). ## Key Parameters - `AUTH_TOKEN_TTL` — browser session/JWT lifetime, default 30 days (`720h`); applies only to tokens issued after the change. - `RESEND_API_KEY` / `RESEND_FROM_EMAIL` and `SMTP_HOST` (+ `SMTP_PORT`, `SMTP_USERNAME`, `SMTP_PASSWORD`, `SMTP_TLS`, `SMTP_TLS_INSECURE`, `SMTP_EHLO_NAME`) — email delivery backends; SMTP wins when both are set. - `MULTICA_DEV_VERIFICATION_CODE` + `APP_ENV` — fixed local test code, ignored in production; never set on a publicly reachable instance. - `ALLOWED_EMAILS`, `ALLOWED_EMAIL_DOMAINS`, `ALLOW_SIGNUP` — signup gating, evaluated in that precedence order. - PAT prefix `mul_`, expiry choices of 30 days / 90 days / 1 year / never (90-day default), auto-renewal inside 7 days of expiry. - Temporary run-token prefix `mat_`, hard cap of 24 hours, task-scoped. - Reserved internal prefixes `mcn_` (Cloud Node) and `mdt_` (daemon auth protocol) — never constructed by end users. ## When To Use Configure email (Resend or SMTP) and signup restrictions before exposing a self-hosted instance publicly — see [[concepts/self-hosting]] for the deployment context. Use a PAT (via `multica login`) whenever scripting against the API, running the CLI, or connecting the daemon; use `multica login --token` on headless/browser-less machines. Tighten `ALLOWED_EMAIL_DOMAINS` / `ALLOWED_EMAILS` and set `ALLOW_SIGNUP=false` for a private company instance; combine with `DISABLE_WORKSPACE_CREATION` (see [[concepts/configuration]]) if every workspace must be admin-controlled. ## Risks & Pitfalls - Don't put a PAT in repositories, issues, comments, screenshots, or logs, and don't pass it directly in shell commands that get saved — it represents the whole account (raw/github_doc-apps-docs-content-docs-auth-tokens-mdx.md). - Never enable `MULTICA_DEV_VERIFICATION_CODE` on a publicly reachable instance — anyone who knows a target email can then sign in with the fixed code (raw/github_doc-apps-docs-content-docs-auth-setup-mdx.md). - `multica auth logout` and web logout only clear locally-stored credentials (the CLI profile's PAT, or the browser's cookies) — neither revokes the PAT on the server. A possibly-leaked token must be revoked explicitly under **Settings → API Token**; revocation immediately invalidates it everywhere it was saved (raw/github_doc-apps-docs-content-docs-auth-tokens-mdx.md). - `ALLOW_SIGNUP=true` with an allowlist configured does **not** mean "allow everyone" — any allowlist configured turns on an implicit deny for non-matches, which is a common misconfiguration surprise. - Don't construct or expect to manage `mcn_`/`mdt_` tokens directly — they belong to internal server/Cloud Fleet flows, not user-side CLI or daemon usage. ## Related Concepts - [[concepts/members-and-roles]] — invitations interact with signup restrictions described here. - [[concepts/security-model]] — how the `mat_` temporary run token limits what an agent can reach. - [[concepts/self-hosting]] — where these environment variables are actually set (`.env`, Compose, Helm). - [[concepts/configuration]] — the full environment-variable reference these settings belong to. ## Sources - raw/github_doc-apps-docs-content-docs-auth-setup-mdx.md - raw/github_doc-apps-docs-content-docs-auth-tokens-mdx.md --- title: "Autopilots" type: concept tags: [agents, workflow, advanced, user, well-established] created: 2026-08-10 updated: 2026-08-10 sources: ["raw/github_doc-apps-docs-content-docs-autopilots-mdx.md"] confidence: high multica_version: "v0.4.22" --- ## Definition An Autopilot runs recurring work automatically — a daily progress summary, a periodic dependency check, or an agent kicked off by an event from an external system. Each autopilot stores a Runbook, an assignee, and one or more triggers; when triggered, Multica either creates an issue or runs the agent directly, and keeps a record of every run (raw/github_doc-apps-docs-content-docs-autopilots-mdx.md). ## How It Works **Creating an autopilot** (Autopilot page in the sidebar, pick a template or start from scratch) configures: Name (what it's responsible for), Runbook (goal, background, constraints, and steps read on every run), Assignee (an agent or a squad), Project (optional — puts auto-created issues into a specific project), Execution mode, Subscribers (notified after an issue is auto-created), and Triggers (schedule or webhook). An autopilot is enabled by default after saving; **Run now** executes the full flow once, manually, at any time. **Execution modes:** | Mode | Behavior | Best for | |---|---|---| | Create issue | Each trigger creates an issue first, then assigns it — discussion, status, and run records all live on the issue | Work the team needs to review, confirm, or follow up on | | Run only | Creates a task directly with no issue; results are visible only in the autopilot's run history | Background runs needing no collaboration record | Create-issue mode uses the same task queue as regular issues — if the runtime is offline, the issue is still created and waits. Run-only mode requires the runtime available at trigger time; otherwise the run shows as skipped and nothing is left behind. **Scheduling**: the schedule editor sets run time, repeat days, time window, and timezone, and previews upcoming run times. One autopilot can have multiple schedules; enabling/disabling an individual trigger uses the CLI's `autopilot trigger-update`. For finer control, edit the standard 5-field cron directly (`minute hour day month weekday`), e.g. `0 9 * * 1-5` in `Asia/Shanghai` = 9:00 on weekdays, `*/30 * * * *` in `UTC` = every 30 minutes. Cron has no seconds field; timezones use IANA names. **Webhook trigger**: adding one generates a unique URL: ```bash curl -X POST "$MULTICA_WEBHOOK_URL" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: demo-001" \ -d '{"event":"build.completed","eventPayload":{"status":"success"}}' ``` The payload is saved on the delivery and run records and handed to the agent (appended to the issue description in create-issue mode). Constraints: body must be a valid JSON object or array up to 256 KiB; `Idempotency-Key` prevents duplicate runs on sender retry (GitHub deliveries are additionally deduped by `X-GitHub-Delivery`); without a stable idempotency key, repeated requests are not guaranteed to run only once; a disabled trigger or non-matching event is recorded as ignored with no run created. **Event filters**: when one source sends several event types, add filters — each row holds one event name plus an optional list of actions; a run fires if any row matches, and leaving all rows empty accepts every event. Multica recognizes event/action from common headers and payload fields, including GitHub's `X-GitHub-Event` and the body's `action` field. Inference order: (1) a string `event` field in the body; (2) `X-GitHub-Event` header combined with the body's `action` into `github..`; (3) `X-Gitlab-Event` header; (4) `X-Event-Type` header; (5) the body's `event`/`type`/`action` fields; (6) otherwise recorded as `webhook.received`. **Webhook responses:** | HTTP status | Response status | Meaning | |---|---|---| | 200 | `accepted` | Run created; returns delivery and run IDs | | 200 | `skipped` | Accepted but skipped (e.g. runtime offline in run-only mode); includes reason | | 200 | `ignored` | No run created — trigger disabled, autopilot paused/archived, or event filtered | | 200 | `duplicate` | Idempotency key hit an existing delivery; original delivery ID returned | | 400 | Error message | Body empty, not valid JSON, or not an object/array | | 401 | `rejected` | Signing secret configured but signature missing/mismatched | | 404 | Error message | URL token invalid or rotated | | 413 | Error message | Body exceeds 256 KiB | | 429 | Error message | Too many requests; retry per `Retry-After` | | 500 | Error message | Multica internal error; sender can retry | Business-level ignores (pausing, archiving, event filtering) return 200 rather than 4xx so senders don't retry endlessly. A fully processed webhook delivery can be replayed from its detail view — this creates a new delivery/run without rewriting the original, and does not participate in deduplication; deliveries that failed signature verification or are still queued can't be replayed. **Failures, pausing, deletion**: run-only failures are not retried automatically, and the next schedule still fires as planned; create-issue mode produces regular issue tasks and follows the standard task retry rules (see [[concepts/board-and-work-items]]). Multica periodically checks recent run health: if the past 7 days have at least 50 completed or failed runs with a 90% failure rate, the system pauses the autopilot and notifies its creator — it must be fixed and resumed manually. Pausing manually stops schedules, webhooks, and Run now. Deletion is actually archiving — future triggers stop, but run and delivery history is kept. **CLI:** ```bash multica autopilot trigger multica autopilot runs multica autopilot trigger-rotate-url ``` ## Key Parameters - Execution modes: `create issue` vs. `run only`. - Cron format: 5-field, no seconds, IANA timezone names. - Webhook payload cap: 256 KiB. - Auto-pause threshold: ≥50 runs in 7 days at ≥90% failure rate. - Deletion is archival, not destructive to history. ## When To Use Use **create issue** mode for anything the team should review or discuss — it puts the run on the board with full history. Use **run only** for background checks that don't need a collaboration record. Use a schedule for time-based recurrence (standups, weekly audits) and a webhook for event-driven triggers from external systems like CI or GitHub. ## Risks & Pitfalls - The token embedded in a webhook URL is the calling credential — do not paste the full URL into public repositories, issues, or screenshots; if it leaks, use **Rotate URL** immediately, which invalidates the old URL right away (raw/github_doc-apps-docs-content-docs-autopilots-mdx.md). - Run-only mode has no automatic retry and leaves nothing behind on a skipped run if the runtime is offline at trigger time — this can silently create gaps in coverage for time-sensitive checks. - Without a stable `Idempotency-Key`, repeated webhook requests are not guaranteed to run only once. - Only the autopilot's creator, workspace owners/admins, and granted collaborators can view the full webhook URL; the UI hides the token by default. - Sustained failure (≥90% over 7 days with ≥50 runs) auto-pauses the autopilot — a silent stoppage that needs manual investigation and resumption. ## Related Concepts - [[concepts/board-and-work-items]] — task retry rules that apply to create-issue mode autopilot runs. - [[concepts/assigning-issues]] — assignment as a trigger source, contrasted with Autopilot's schedule/webhook triggers. - [[concepts/squads]] — an autopilot's executor can point at a squad instead of a single agent. - [[concepts/getting-started]] — the tutorial's worked example of creating a weekly review autopilot. - [[concepts/core-concepts]] — Autopilot as one of four trigger sources alongside assignment, mention, and chat. ## Sources - raw/github_doc-apps-docs-content-docs-autopilots-mdx.md --- title: "Board and Work Items" type: concept tags: [board, workflow, foundational, user, well-established] created: 2026-08-10 updated: 2026-08-10 sources: ["raw/github_doc-apps-docs-content-docs-projects-mdx.md", "raw/github_doc-apps-docs-content-docs-workspaces-mdx.md", "raw/github_doc-apps-docs-content-docs-tasks-mdx.md", "raw/github_doc-apps-docs-content-docs-issues-mdx.md"] confidence: high multica_version: "v0.4.22" --- ## Definition Multica organizes work in a hierarchy: a **workspace** is the top-level, isolated boundary for a team; **projects** group related **issues** under one goal; each **issue** is the basic day-to-day unit of work with a status, assignee, and history; and each agent run against an issue produces a **task**, the concrete execution record. Work moves across the board as issue status changes, while tasks record the individual agent runs behind that movement. ## How It Works **Workspace** (raw/github_doc-apps-docs-content-docs-workspaces-mdx.md) is Multica's top-level boundary — members, issues, projects, agents, skills, and task history all belong to one workspace and are fully isolated from every other. It holds: Work (issues, projects, comments, attachments, task history), Team (members, roles, invitations), Agents (agent configuration, skills, runtimes, automations), and Shared settings (context, labels, custom properties, integrations). Creating a workspace needs a name and a URL slug (e.g., the `my-team` in `multica.ai/my-team`) that cannot be changed afterward; the creator automatically becomes `owner`. The issue prefix (e.g., `MUL`) is generated from the workspace name, and issue numbers count up independently within the workspace. **Project** (raw/github_doc-apps-docs-content-docs-projects-mdx.md) organizes work that takes multiple issues to finish — a launch, a migration, a feature delivered in stages. A single issue that stands alone does not need a project. Parts of a project: name/icon/description (the description enters the execution context of agents working inside it), status (`planned`, `in_progress`, `paused`, `completed`, `cancelled`), priority (`urgent`, `high`, `medium`, `low`, `none`), lead (a member or agent who coordinates but does not auto-run anything), start/target dates, issues and progress, and resources (linked GitHub repositories or local directories on specific computers). An issue belongs to at most one project; progress is computed automatically as: ```text progress = issues in done or cancelled ÷ all issues in the project ``` Project status and issue status are independent — finishing every issue does not auto-complete the project, and changing project status does not bulk-change issues. Any workspace member can create/edit projects; only `owner` and `admin` can delete them, and deleting a project detaches its issues (they stay in the workspace) while permanently deleting the project's own description, status, and resources. **Issue** (raw/github_doc-apps-docs-content-docs-issues-mdx.md) is Multica's basic unit of work — a feature, bug, or investigation, numbered like `MUL-123`. Its parts: title/description (goal, background, requirements, acceptance criteria), status/priority, assignee (member, agent, or squad), dates/labels/custom properties, project and parent-child relationships, and an activity/execution log. Choosing an assignee has different effects: assigning a **member** just gives them ownership (no task created); assigning an **agent** creates a task; assigning a **squad** routes to the leader, who decides who handles it. When assigned to an agent or squad, the issue enqueues immediately unless it is in `backlog`. Issue statuses: `backlog` (not starting yet — no task is created until it leaves backlog), `todo`, `in_progress`, `in_review`, `done`, `blocked`, `cancelled`. There is no fixed flow between statuses; agents are expected to move `backlog`/`todo` → `in_progress` on start, then `in_review` on delivery, written explicitly via the Multica CLI — the server itself only changes status in two cases: a failed run with no other active/retry task rolls `in_progress` back to `todo`, and a linked GitHub PR merging with close intent (no other open/draft linked PR) sets the issue to `done`. Larger work splits into sub-issues, which can be grouped into stages (1, 2, 3…) that advance in batches; when every sub-issue in the earliest unfinished stage reaches `done`/`cancelled`, the parent gets a "sub-issues completed" notification. The Issues page offers five views — list, board, table, Gantt, swimlane — all showing the same issues. **Task** (raw/github_doc-apps-docs-content-docs-tasks-mdx.md) records one agent run: what triggered it, which agent, how far it progressed, and whether it succeeded. An issue holds the goal/discussion/assignee/final status of a piece of work and can span many runs; a task runs from trigger to completion/failure/cancellation, and earlier task records are never overwritten. Trigger sources: assigning an issue to an agent/squad, mentioning an agent in a comment, chatting with it directly, or an Autopilot firing. Execution lifecycle states: `deferred` → `queued` → `dispatched` → (`waiting_local_directory` if needed) → `running` → `completed`/`failed`/`cancelled`. A task left unclaimed over 2 hours ends as failed; `dispatched` over 5 minutes is treated as failed; `running` has no fixed cap, following the runtime's 15-second heartbeat (offline detection within about 3 minutes). Regular tasks retry automatically at most twice by default for transient faults (runtime offline, daemon restart reclaim, platform timeout, Codex stalled, skill download failure); tool network interruptions get up to three attempts. Agent-side errors (auth, quota, config, model) are not auto-retried and need the cause fixed first. From the Execution log you can open a run's transcript, stop active tasks, or retry a failed/cancelled one; `multica issue rerun ` starts a fresh session/working directory against the issue's current assignee. ## Key Parameters - Workspace slug is permanent; issue prefix can be changed later by `owner`/`admin` but old references in PRs, branches, and chat history do not update (raw/github_doc-apps-docs-content-docs-workspaces-mdx.md). - Project progress formula: `done + cancelled ÷ total issues`. - Issue statuses: `backlog`, `todo`, `in_progress`, `in_review`, `done`, `blocked`, `cancelled`. - Task states: `deferred`, `queued`, `dispatched`, `waiting_local_directory`, `running`, `completed`, `failed`, `cancelled`. - Retry ceilings: 2 attempts by default for platform-side transient faults, up to 3 for tool network interruptions. ## When To Use Use a **project** when work spans several issues sharing a goal, tracked progress, or shared resources; a single issue that stands alone doesn't need one. Use **sub-issues with stages** when a larger issue's work must advance in controlled batches. Consult the **execution log** on an issue whenever a run's outcome, cost, or failure reason needs to be understood before deciding to retry or reassign. ## Risks & Pitfalls - Changing an issue's assignee or status does not stop an already-started run — the corresponding task must be stopped explicitly in the execution log (raw/github_doc-apps-docs-content-docs-tasks-mdx.md, raw/github_doc-apps-docs-content-docs-issues-mdx.md). - Deleting an issue is irreversible and cancels unfinished tasks; use `cancelled` status instead when the work is simply no longer pursued (raw/github_doc-apps-docs-content-docs-issues-mdx.md). - Deleting a project does not delete its issues (they detach and remain), but does permanently delete the project's own description, status, and resources (raw/github_doc-apps-docs-content-docs-projects-mdx.md). - `completed` on a task only means that one run ended normally — it says nothing about whether the issue's actual goal was met (raw/github_doc-apps-docs-content-docs-tasks-mdx.md, raw/github_doc-apps-docs-content-docs-issues-mdx.md). See [[concepts/multica-overview]]. - The last workspace `owner` cannot leave without promoting someone else first, and leaving a workspace deactivates owned runtimes, archives their bound agents, and cancels unfinished tasks (raw/github_doc-apps-docs-content-docs-workspaces-mdx.md). ## Related Concepts - [[concepts/core-concepts]] — where workspace/project/issue/task sit in the full domain model. - [[concepts/assigning-issues]] — how an issue becomes a task for a specific agent or squad. - [[concepts/squads]] — what happens when an issue's assignee is a squad rather than a single agent. - [[concepts/autopilots]] — a fourth trigger source for tasks, alongside assignment, mention, and chat. - [[concepts/multica-overview]] — the review-gate philosophy behind issue statuses and task completion. ## Sources - raw/github_doc-apps-docs-content-docs-projects-mdx.md - raw/github_doc-apps-docs-content-docs-workspaces-mdx.md - raw/github_doc-apps-docs-content-docs-tasks-mdx.md - raw/github_doc-apps-docs-content-docs-issues-mdx.md --- title: "Chat Integrations" type: concept tags: [integrations, communication, self-hosting] created: 2026-08-10 updated: 2026-08-10 sources: ["raw/github_doc-apps-docs-content-docs-slack-bot-integration-mdx.md", "raw/github_doc-apps-docs-content-docs-lark-bot-integration-mdx.md", "raw/github_doc-apps-docs-content-docs-dingtalk-bot-integration-mdx.md", "raw/github_doc-apps-docs-content-docs-channels-mdx.md"] confidence: high multica_version: "v0.4.22" --- ## Definition Chat integrations connect a Multica [agent](/agents) to a bot in an external chat platform — Slack, Feishu/Lark, or DingTalk (WeCom also exists but is out of scope here) — so a team can DM the agent, @-mention it in a group/channel, or create an issue with `/issue`, without opening Multica. Each bot maps to exactly **one** agent; connecting several agents to the same platform means creating a separate bot per agent. Slack and Feishu/Lark are officially supported; DingTalk (like WeCom) is community-maintained, shipping in every release but with no official support SLA. ## How It Works **Slack** uses a Multica-authored app manifest that a workspace owner/admin pastes into Slack when creating the app (`Create New App → From a manifest`). The manifest defines the bot's scopes (`app_mentions:read`, `channels:history`, `chat:write`, `commands`, etc.), the `/issue` slash command, and enables Socket Mode — so no public Request URL is needed. Connecting requires two credentials pasted into Multica: a Bot User OAuth Token (`xoxb-...`, from **Install App**) and an App-level Token (`xapp-...`, generated under **Basic Information → App-Level Tokens** with the `connections:write` scope). Multica verifies both come from the same app before showing **Connected to Slack**. In Slack, DM the bot directly (no mention needed), or `/invite @your-bot` into a channel and then `@your-bot ` — each thread is its own session, and follow-ups need a fresh @-mention in that thread. `/issue ` needs no mention; the agent behind the bot writes up the title and body itself before creating the issue, and Slack shows a private acknowledgment while the issue is created asynchronously. **Feishu/Lark** is a scan-to-install flow: open the target agent's **Integrations** tab, click **Bind to Feishu**, and scan the shown QR code (a one-time credential) with Feishu to authorize. New connections are currently open only for **mainland-China Feishu**; existing **international Lark** connections keep working and can still be managed. DMs stay in one continuing conversation; group chats require adding the bot and then `@Bot ` per turn. `/issue` here uses a two-part message: the first line becomes the title, the rest becomes the description; sending `/issue` alone gets a format-reminder reply instead of creating anything. **DingTalk** is bring-your-own-app (BYO): a workspace admin creates an "enterprise internal app" on the DingTalk Open Platform, adds the **robot** capability, sets its message-receiving mode to **Stream mode** (a long-lived outbound push connection — no public webhook/URL, no OAuth), grants it message-read and message-send scopes, then copies its **AppKey** (client id) and **AppSecret** (client secret) into Multica's agent **Integrations** tab. Each agent needs its own DingTalk app. DingTalk has no native typing/reaction indicator, so the bot posts a short "working on it" acknowledgment when a run starts, coalescing a quick burst of messages into one acknowledgment, with the full reply following once the agent finishes. DingTalk additionally supports images (PNG/JPEG/GIF/WebP/BMP, up to 4 per message, 10 MB each, copied into Multica storage so they outlive DingTalk's temporary link) and a `/new ` command that runs without prior conversation context (a bare `/new` primes the next non-empty message the same way, without creating an empty turn, and stays pending until a chat task is actually queued) — conversation history is preserved either way. **Shared mechanics across all three (and WeCom).** A bot resolves to one workspace + one agent. In a group/channel, only messages that explicitly @-mention the bot are read and acted on — the bot never listens to the whole channel; DMs need no mention. Every message re-checks the sender's account binding and workspace membership before the agent runs. The first time a member messages a bot, they get a single-use account-binding link (Slack/DingTalk: expires in ~15 minutes) that ties the platform identity to their Multica membership in that workspace; account binding only confirms identity — it does not add other chat-platform users to the Multica workspace. `/issue` is a command, not a chat turn: it is not added to Multica Chat, only the resulting issue is recorded. Session isolation differs slightly by platform (see [[concepts/communication]]): Feishu/Lark and WeCom key sessions by chat, Slack by thread, DingTalk by conversation. ## Key Parameters - One bot ↔ one agent (all three platforms); connect multiple bots to run multiple agents on the same platform. - Self-hosting requires a 32-byte base64 encryption key per platform: `MULTICA_SLACK_SECRET_KEY`, `MULTICA_LARK_SECRET_KEY`, `MULTICA_DINGTALK_SECRET_KEY` (generate with `openssl rand -base64 32`); Multica Cloud has these pre-configured. - Account-binding link lifetime: ~15 minutes, single-use, built from `MULTICA_APP_URL` (falling back to `FRONTEND_ORIGIN`). - Connect/disconnect permission: workspace owner or admin for all platforms; for Feishu/Lark, the agent's own owner can also connect/disconnect its bot. - DingTalk image limits: up to 4 images per message, 10 MB each, formats PNG/JPEG/GIF/WebP/BMP; files and voice are unsupported. - DingTalk-only commands: `/issue ` (description on following lines) and `/new [message]`. ## When To Use - Use **Slack** when the team already lives in Slack and wants `/issue` plus @-mention access to a specific agent per channel. - Use **Feishu/Lark** for mainland-China Feishu teams (new connections) or to keep maintaining an existing international Lark bot. - Use **DingTalk** when the organization standardizes on DingTalk and is comfortable with a community-maintained integration and a BYO-app setup step per agent. - Prefer plain [[concepts/communication|Multica chat]] instead when privacy (no platform account binding, no external message flow) matters more than platform convenience. ## Risks & Pitfalls - Removing scopes or events from the Slack manifest before creating the app can silently break DMs, mentions, replies, or `/issue`. - Both Slack tokens must come from the same app; an app already connected to another agent or workspace can't be reused until disconnected first. - The Feishu/Lark and Slack/DingTalk binding links and QR codes expire quickly (QR: single-use; links: ~15 minutes) — expired links require re-sending a message or regenerating the code, not retrying the old one. - DingTalk messages from non-members, or members who skip identity linking, are silently dropped — the message body is never stored, only a drop reason for audit. - Losing or rotating a platform's `MULTICA_*_SECRET_KEY` makes already-stored bot credentials permanently undecryptable, forcing every bot on that platform to reconnect. - Channel/group bots only ever see the @-mentioning message, never the full channel history — assuming the agent has broader context than that is a common mistake. - DingTalk's robot needs explicit **send** permission separately from receive scopes; without it, the agent runs but its reply can never be delivered. ## Related Concepts - [[concepts/communication]] — chat, comments, and inbox mechanics that these bots feed into. - [[concepts/vcs-integration]] - [[concepts/agents]] - [[concepts/self-hosting]] - [[concepts/security-model]] ## Sources - raw/github_doc-apps-docs-content-docs-slack-bot-integration-mdx.md - raw/github_doc-apps-docs-content-docs-lark-bot-integration-mdx.md - raw/github_doc-apps-docs-content-docs-dingtalk-bot-integration-mdx.md - raw/github_doc-apps-docs-content-docs-channels-mdx.md <!-- ===== multica/wiki/concepts/cli-and-daemon.md ===== --> --- title: "CLI and Daemon" type: concept tags: [cli, workflow, self-hosting] created: 2026-08-10 updated: 2026-08-10 sources: ["raw/github_doc-cli-and-daemon-md.md", "raw/github_doc-cli-install-md.md", "raw/github_doc-apps-docs-content-docs-cli-mdx.md", "raw/github_doc-apps-docs-content-docs-daemon-runtimes-mdx.md"] confidence: high multica_version: "v0.4.22" --- ## Definition The `multica` CLI is the single binary that both connects a local machine to Multica (authentication, workspace management, issue/project/agent management from the terminal) and runs the **agent daemon** — the background process that detects installed AI coding tools, claims tasks assigned to agents, and executes them on that machine. The daemon is what turns a computer into one or more **runtimes**: one runtime per detected AI coding tool (or custom runtime profile) per workspace. ## How It Works **Installation.** macOS/Linux: `brew install multica-ai/tap/multica`, or `curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash`, or build from source (`git clone ... && make build && cp server/bin/multica /usr/local/bin/multica`). Windows: `irm https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.ps1 | iex` in PowerShell, which installs to `%USERPROFILE%\.multica\bin\` and updates the user PATH (Scoop is used automatically if present: `scoop bucket add multica https://github.com/multica-ai/scoop-bucket.git && scoop install multica`). Verify with `multica version`. Upgrade via `brew upgrade multica-ai/tap/multica`, or `multica update` (auto-detects the install method). **First connection.** ```bash multica setup # Multica Cloud: configure, authenticate, start the daemon multica setup self-host --server-url https://api.example.com --app-url https://app.example.com ``` `multica setup` saves the server address, opens a browser for OAuth sign-in, and starts the daemon in one step; `multica login` re-authenticates without touching other configuration; `multica login --token <mul_...>` (or `--token` with no value, to be prompted so the token never lands in shell history) supports headless environments using a personal access token generated at `https://multica.ai/settings?tab=tokens`. `multica login` auto-discovers every workspace the account belongs to and adds them to the daemon watch list. Check results with `multica auth status` and `multica daemon status`. **The daemon.** `multica daemon start` runs it in the background, logging to `~/.multica/daemon.log` (`--foreground` for debugging). On startup it detects supported AI CLIs on `PATH` and registers a runtime per detected tool per watched workspace; restarting updates existing runtime records rather than duplicating them. It needs at least one supported CLI detected before it will start. Once registered, a runtime keeps a persistent connection: the server pushes new tasks to it, and the daemon also polls periodically (default 3s) as a backstop. A heartbeat every 15s (default) tells the server the daemon is alive; after an unexpected exit, the runtime typically shows offline within about 3 minutes. Queued tasks wait for an offline runtime to recover for up to 2 hours; running tasks fail and eligible ones retry automatically; on restart the daemon re-registers and reclaims tasks that didn't end cleanly. A runtime offline for 7+ days with no agents bound (including archived ones) is cleaned up automatically. Concurrency defaults to 20 tasks per daemon and 6 per agent — effective concurrency is the smaller of the two, adjustable via agent settings and `MULTICA_DAEMON_MAX_CONCURRENT_TASKS`. A CLI-launched daemon also follows its own binary: it compares its compile-time version against the `multica` binary on disk, and after any running task finishes, restarts into a newer version from `brew upgrade`, a re-download, or a local `make build` (disable with `MULTICA_DAEMON_AUTO_RELOAD=0`, `--no-auto-reload`, or `multica config set disable_auto_reload true`). This is independent of the separate GitHub self-update poller. Agent CLIs themselves (codex, claude, ...) are re-probed and re-registered in place when upgraded, with no daemon restart. Desktop-managed daemons ignore both mechanisms — Desktop owns its bundled CLI's lifecycle (see [[concepts/desktop-and-mobile-apps]]). **Runtimes vs daemon.** The daemon is the process; a runtime is one execution environment it exposes — one computer + one AI coding tool, or one custom runtime profile on that computer. All local tool logins, code directories, and execution happen on the connected computer; the server never executes commands itself and never auto-uploads the whole working directory, though issues, comments, agent config, task context, and run results (which can include code snippets an agent chose to surface) do live server-side, and an agent's custom environment variables/MCP config are stored server-side and sent to the runtime at execution time. Runtimes are **private** by default (owner + workspace owners/admins can create agents on it); the owner or an admin can make one **public** so other members can route tasks to it — without sharing the underlying tool's own login. **Custom runtime profiles** (workspace owners/admins only) wrap an internal script, a version-pinned executable, or fixed extra arguments for a protocol family Multica already supports; the command field takes an executable and arguments only — no pipes, redirects, `&&`, or shell expansion (put those in a wrapper script). `multica runtime profile set-path/unset-path <profile-id>` pins or clears a local absolute path per computer, useful when a Desktop-launched daemon can't resolve a command a terminal can. **CLI command surface.** Everything is grouped under top-level nouns — `issue`, `project`, `label`/`property`, `agent`/`skill`/`squad`, `autopilot`, `workspace`, `repo`, `daemon`/`runtime`, `attachment`, `user profile`, `auth`/`login`/`setup`, `config`, `update`/`version`, and `chat` (reads the external chat session an agent is currently handling — not general conversation browsing). All commands accept `--server-url`, `--workspace-id`, `--profile`, `--debug`; `--output json` is the scripting-safe format (tables are terminal-oriented and shouldn't be parsed). Workspace resolution order: `--workspace-id` flag > `MULTICA_WORKSPACE_ID` env var > the profile's stored default (set via `multica workspace switch` or `multica login`). `--profile <name>` isolates a full separate config, token, default workspace, and daemon state under `~/.multica/profiles/<name>/config.json`; the unnamed default lives at `~/.multica/config.json`. Selected everyday commands: ```bash multica issue list --status in_progress --sort created_at --direction desc multica issue create --title "Fix login bug" --priority high --assignee "Lambda" multica issue assign <id> --to "Lambda" multica issue status <id> in_progress multica issue comment add <issue-id> --content "Looks good, merging now" multica issue metadata set <issue-id> --key pr_number --value 482 multica issue reorder <id> --top multica workspace switch <id|slug> multica agent list multica skill import --url <skill-url> --on-conflict rename multica daemon status --output json multica runtime list ``` Issues route by key (`MUL-123`) or full UUID — short UUID prefixes are rejected for issues specifically, though other resources' `list` commands print copyable short IDs (with `--full-id` for the canonical UUID) and the CLI asks for more characters when a short ID is ambiguous. **Task-scoped CLI (agent context).** When the CLI runs inside a daemon-managed agent task, it authenticates with a task-scoped credential the daemon injects rather than loading the human's profile files, and human/local-only subcommands (`login`, `logout`, `setup`, `workspace switch`, local runtime profile path changes, `daemon start`/`stop`/`restart`/`logs`/`probe-runtimes`) are unavailable; `auth status` won't print token material there. `daemon status` and `daemon disk-usage` remain available, scoped to the hosting runtime only (no `--profile`; `disk-usage` also rejects `--all-profiles`/`--workspaces-root` and shows a blank STATUS column). This is a CLI-profile-resolution boundary, not an OS filesystem boundary — a process running as the same system user can still open a known path explicitly; use a dedicated user/container/VM for a stronger guarantee. **Errors and exit codes.** Errors funnel through one translation layer into a single friendly sentence with a next step (transport failures, HTTP status failures); a 400/422 with a server message shows it verbatim as `Invalid request: <message>`. `--debug` (or `MULTICA_DEBUG=1`) prints the full original error chain. Exit codes are tiered for scripting: `0` success, `1` generic error, `2` network error, `3` auth (401/403), `4` not found (404), `5` validation (400/422). Messages default to English and switch to Chinese only when `LC_ALL`/`LC_MESSAGES`/`LANG` (in that order) indicate a Chinese locale. ## Key Parameters - `MULTICA_DAEMON_POLL_INTERVAL` (default `3s`), `MULTICA_DAEMON_HEARTBEAT_INTERVAL` (default `15s`), `MULTICA_AGENT_TIMEOUT` (default `0`, no cap), `MULTICA_DAEMON_MAX_CONCURRENT_TASKS` (default `20`). - `MULTICA_WORKSPACES_ROOT` (default `~/multica_workspaces`) and the `MULTICA_GC_*` family controlling workspace garbage collection (task cleanup TTL, orphan TTL, artifact TTL/patterns, repo-cache TTL, Hermes memory TTL). - Per-agent overrides: `MULTICA_<AGENT>_PATH`, `MULTICA_<AGENT>_MODEL`, and (for some) `MULTICA_<AGENT>_ARGS`, covering Claude, Codex, CodeBuddy, DevEco, OpenCode, OpenClaw, Hermes, Pi, Cursor, Kimi, Reasonix, Kiro, Qoder/Qoder CN, Trae, Grok, Qwen, and QwenPaw. - `MULTICA_HTTP_TIMEOUT` (default `30s`) for API request timeouts. - `MULTICA_DAEMON_AUTO_RELOAD` / `--no-auto-reload` / `disable_auto_reload` config key — controls whether the daemon follows a replaced `multica` binary. - CLI workspace resolution precedence: `--workspace-id` > `MULTICA_WORKSPACE_ID` > profile default. ## When To Use - Install the CLI on any machine you want to contribute execution capacity to a workspace — a laptop, a build server, or a headless CI box. - Use `multica setup self-host` for a first connection to a self-hosted server; use `multica login` alone to just re-authenticate. - Use `--profile <name>` when one machine needs isolated credentials/config for multiple organizations or a staging vs. production server. - Use `--output json` for anything scripted; never parse table output. - Use a **custom runtime profile** when the team needs a version-pinned or wrapped agent CLI rather than the bare on-PATH binary. ## Risks & Pitfalls - The daemon needs at least one supported AI CLI detected on `PATH` before it will start at all — a fresh machine with none installed can't run the daemon. - Restarting the daemon after installing or updating a tool is required to pick up detection changes; a tool installed mid-session won't be found until then. - `config set workspace_id <id>` writes the value without checking access — prefer `multica workspace switch` which validates access first. - CLI configuration files contain tokens that authenticate as the user; never commit them or paste them into logs. - Inside a daemon-managed agent task, most human-only CLI subcommands (login, daemon start/stop, workspace switch, etc.) are unavailable by design — don't expect agent-run CLI calls to manage the daemon itself. - The task-scoped-credential isolation is a CLI convenience boundary, not a hard OS sandbox — a same-user process can still reach a known path explicitly. - A runtime offline for more than 7 days with no bound agents (even archived ones) is auto-cleaned; queued tasks against an offline runtime wait only up to 2 hours before failing. - The command field for a custom runtime profile rejects pipes, redirects, `&&`, `;`, backticks, and env-var expansion — those need a wrapper script instead. ## Related Concepts - [[concepts/desktop-and-mobile-apps]] — Desktop starts and manages its own bundled daemon automatically. - [[concepts/providers-and-runtimes]] - [[concepts/auth-and-tokens]] - [[concepts/self-hosting]] - [[concepts/configuration]] - [[concepts/troubleshooting]] ## Sources - raw/github_doc-cli-and-daemon-md.md - raw/github_doc-cli-install-md.md - raw/github_doc-apps-docs-content-docs-cli-mdx.md - raw/github_doc-apps-docs-content-docs-daemon-runtimes-mdx.md <!-- ===== multica/wiki/concepts/communication.md ===== --> --- title: "Communication" type: concept tags: [communication, board, workflow] created: 2026-08-10 updated: 2026-08-10 sources: ["raw/github_doc-apps-docs-content-docs-channels-mdx.md", "raw/github_doc-apps-docs-content-docs-chat-mdx.md", "raw/github_doc-apps-docs-content-docs-comments-mdx.md", "raw/github_doc-apps-docs-content-docs-inbox-mdx.md"] confidence: high multica_version: "v0.4.22" --- ## Definition Communication in Multica is how humans and agents exchange information about work. It has four parts: **[[concepts/chat-integrations|chat integrations]]** (external chat platforms like Slack, Feishu/Lark, and DingTalk), one-to-one **chat** with an agent outside any issue, **comments** attached to an issue where ongoing collaboration happens, and the **inbox**, which surfaces the subset of activity that needs a member's attention. Each channel has a distinct scope: chat is private and issue-free, comments are shared and issue-bound, and the inbox is a personal notification feed built from both. ## How It Works **Chat** is a private, one-to-one conversation between a member and an [agent](/agents), started from the **Chat** sidebar item. It carries **no issue context** by default — the agent isn't looking at the board and won't turn the conversation into issues on its own — though a member can attach a **project** as background context (click **+** → **Project context**), giving the agent that project's description, repositories, and resources for the run. Multica tries to continue the same underlying AI-tool session across turns by storing the session ID; if that session can't be resumed, the runtime starts fresh but keeps the visible message history. Conversations can be pinned, archived (made read-only), unarchived, or deleted; archiving a conversation bound to an external channel (e.g. Slack) breaks that binding permanently — unarchiving does not restore it. **Comments** live on an issue's activity area and support formatting, code blocks, links, attachments, and threaded replies (nested replies still collapse under one top-level discussion). A discussion can be marked resolved, or a single reply marked as its conclusion; replying to a resolved discussion reopens it automatically. Typing `@` opens a suggestion list with five mention targets: | Target | Effect | |---|---| | Member | Inbox mention notification; does not create a subscription by itself | | Agent | Creates a task for that agent (agents have no inbox) | | Squad | Notifies the squad's members and triggers the squad leader | | Issue | Inserts a link only — no notification, no agent trigger | | `@all` | Notifies every workspace member, triggers no agent | Plain-text `@name` typed without picking from the list creates no mention. Editing a comment recalculates its triggers from the new content, and the trigger preview shows before saving; deleting a top-level comment deletes every reply beneath it (irreversible). **Chat integrations** connect Multica to a team's existing chat tool — Feishu/Lark, Slack, DingTalk, and WeCom are supported (Feishu/Lark and Slack officially, DingTalk and WeCom community-maintained). See [[concepts/chat-integrations]] for setup. All four share the same processing pipeline: a bot resolves to one workspace and one agent; in a group, only messages that explicitly @-mention the bot proceed (DMs need no mention); the sender's account binding and workspace membership are verified on every message; the message joins a chat session and creates a task; the reply is posted back to the originating DM or thread. `/issue` is a command, not a chat turn — Multica posts the created issue back to the platform but does not add the command itself to Multica Chat. **The inbox** collects notifications that need a member's attention — assignments, subscribed-issue changes (comments, assignee, status, priority, dates), @-mentions, reactions on your content, agent run failures on subscribed issues, and autopilot events. It is not a full activity log; it flags what changed, and full context stays on the issue. Automatic subscription sources are: an issue's creator, its assignee, anyone who comments, anyone newly @-mentioned in the description, and an autopilot's preconfigured subscribers. **Agents never use the inbox** — even as assignee or subscriber, an agent's trigger (mention, assignment, autopilot) creates a run directly instead of a notification. Notification groups (assignments, status changes, comments, mentions, priority/dates, agent activity) can be toggled independently under **Settings → Notifications**; a few types (reactions, quick-create results, autopilot pauses) are always delivered regardless. ## Key Parameters - **Session isolation per platform** — Feishu/Lark and WeCom separate sessions by chat; Slack separates by channel (each thread is its own session); DingTalk separates by conversation. A fresh @-mention is required for every follow-up in a channel/group; the agent never reads full channel history automatically. - **Notification groups** — six toggleable categories in Settings → Notifications (assignments, status changes, comments, mentions, priority and dates, agent activity); turning a group off stops inbox delivery only, not the underlying record. - **Mention targets** — member, agent, squad, issue, `@all`, each with different notification/trigger effects (see table above). - **Visibility** — direct chats are visible only to their creator, not even to admins; comments are shared with the whole workspace. ## When To Use - Use **chat** for exploring an approach, brainstorming, private drafts, or a quick workspace lookup that doesn't need a work record. - Use an **issue comment** (not chat) when teammates need to see the background and continue the discussion, or when a clear assignee/status/priority/deliverable is needed. - Use a **chat integration** (Slack/Feishu/Lark/DingTalk) when the team wants to reach an agent without opening Multica, including filing an issue via `/issue` from the chat tool itself. - Check the **inbox** to catch up on what changed across subscribed issues without re-reading every issue. ## Risks & Pitfalls - Archiving a conversation bound to an external channel **permanently** breaks that binding — unarchiving does not restore it. - Deleting a comment or conversation is irreversible; deleting a top-level comment cascades to all of its replies. - Plain-text `@name` (not chosen from the suggestion list) silently creates no mention and triggers nothing. - Turning off a notification group in Settings only stops inbox delivery — the underlying issue history is still recorded, so relying on the inbox alone can miss context already on the issue. - The inbox is member-only: assigning or mentioning an agent never produces an inbox entry for that agent — it produces a run instead. Don't expect agents to "check their inbox." - Channel/group chat integrations only see the @-mentioning message, not the surrounding conversation, unless the platform's own recent-context read applies. ## Related Concepts - [[concepts/chat-integrations]] — Slack, Lark, and DingTalk bot setup and behavior. - [[concepts/vcs-integration]] — how PR activity surfaces on the issue alongside comments. - [[concepts/agents]] - [[concepts/assigning-issues]] - [[concepts/triggering-and-mentioning-agents]] ## Sources - raw/github_doc-apps-docs-content-docs-channels-mdx.md - raw/github_doc-apps-docs-content-docs-chat-mdx.md - raw/github_doc-apps-docs-content-docs-comments-mdx.md - raw/github_doc-apps-docs-content-docs-inbox-mdx.md <!-- ===== multica/wiki/concepts/configuration.md ===== --> --- title: "Configuration" type: concept tags: [self-hosting, operator, workflow, foundational, well-established] created: 2026-08-10 updated: 2026-08-10 sources: ["raw/github_doc-apps-docs-content-docs-environment-variables-mdx.md", "raw/github_doc-apps-docs-content-docs-project-resources-mdx.md"] confidence: high multica_version: "v0.4.22" --- ## Definition Multica's configuration surface has two distinct layers: **environment variables**, read at process startup by the API, web, and daemon processes, which control deployment-level behavior (database, auth, storage, integrations); and **project resources**, which tell agents which code a given body of work uses and where to run, so repository URLs and local paths don't have to be re-pasted into every issue (raw/github_doc-apps-docs-content-docs-environment-variables-mdx.md; raw/github_doc-apps-docs-content-docs-project-resources-mdx.md). ## How It Works ### Environment variables Variables are read once at startup; changing one requires restarting the affected process. `docker compose restart` does **not** re-read `.env` — recreate containers with `up -d` instead. **Minimum production configuration:** ```dotenv DATABASE_URL=postgres://user:password@postgres:5432/multica?sslmode=require JWT_SECRET=<long-random-secret> APP_ENV=production FRONTEND_ORIGIN=https://multica.example.com MULTICA_APP_URL=https://multica.example.com MULTICA_PUBLIC_URL=https://api.multica.example.com ``` An email service must also be picked, or verification codes/invitations are only written to the server log. Never use the default `JWT_SECRET` in production, and never set `MULTICA_DEV_VERIFICATION_CODE` there. **API and database:** `DATABASE_URL`, `DATABASE_MAX_CONNS` (default `25`), `DATABASE_MIN_CONNS` (default `5`), `PORT` (default `8080`), `JWT_SECRET`, `APP_ENV`, `AUTH_TOKEN_TTL` (default `720h`/30 days — see [[concepts/auth-and-tokens]]), `LOG_LEVEL`, `MULTICA_SHUTDOWN_HOLD_DURATION` (default `0`; on Kubernetes, `terminationGracePeriodSeconds` must exceed hold + actual shutdown time). **Public URLs / browser access:** `FRONTEND_ORIGIN` (required for self-hosting — without it, invitation links, cookie security attributes, and WebSocket origin checks can all disagree with the real domain), `MULTICA_APP_URL` (falls back to `FRONTEND_ORIGIN`), `MULTICA_PUBLIC_URL`, `CORS_ALLOWED_ORIGINS`, `ALLOWED_ORIGINS` (WebSocket origin allowlist), and `COOKIE_DOMAIN` — required only when the frontend and API run on different hosts and the browser talks to the API directly (narrowest parent domain covering both, e.g. `.agent.example.com` not `.example.com`; never an IP address). See [[concepts/self-hosting]] for the same-origin vs. split-domain deployment patterns this feeds into. **Email and sign-in** (full behavior in [[concepts/auth-and-tokens]]): Resend (`RESEND_API_KEY`, `RESEND_FROM_EMAIL`, default `noreply@multica.ai`); SMTP (`SMTP_HOST`, `SMTP_PORT` default `25`, `SMTP_USERNAME`, `SMTP_PASSWORD`, `SMTP_FROM_EMAIL` falls back to `RESEND_FROM_EMAIL`, `SMTP_TLS` default `starttls`, `SMTP_TLS_INSECURE` default `false`, `SMTP_EHLO_NAME`) — SMTP takes priority whenever `SMTP_HOST` is non-empty; Google OAuth (`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `GOOGLE_REDIRECT_URI` default `http://localhost:3000/auth/callback`); signup scope (`ALLOW_SIGNUP` default `true`, `ALLOWED_EMAILS`, `ALLOWED_EMAIL_DOMAINS`, `DISABLE_WORKSPACE_CREATION` default `false` — blocks all users from creating workspaces, no owner/admin exception, `MULTICA_DEV_VERIFICATION_CODE`). **Attachment storage:** local disk is used whenever `S3_BUCKET` is unset (`LOCAL_UPLOAD_DIR` default `./data/uploads`, `LOCAL_UPLOAD_BASE_URL`). S3 or compatible: `S3_BUCKET` (name only, not the full hostname), `S3_REGION` (default `us-west-2`), `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY` (default: SDK credential chain), `AWS_ENDPOINT_URL` (e.g. MinIO), `S3_USE_PATH_STYLE` (default `true` with a custom endpoint), `ATTACHMENT_DOWNLOAD_MODE` (`auto` default, `cloudfront`, `presign`, or `proxy` — use `proxy` when the endpoint isn't browser-reachable), `ATTACHMENT_DOWNLOAD_URL_TTL` (default `30m`). CloudFront adds `CLOUDFRONT_DOMAIN`, `CLOUDFRONT_KEY_PAIR_ID`, `CLOUDFRONT_PRIVATE_KEY`, `CLOUDFRONT_PRIVATE_KEY_SECRET` (for reading the key from Secrets Manager). **Redis and rate limiting:** `REDIS_URL` (used for auth rate limiting, realtime events, and the token cache; unset means realtime falls back to in-process memory and auth rate limiting is off), `REDIS_DISABLE_CLIENT_NAME` (default `false`), `RATE_LIMIT_AUTH` (default `5`/min/IP), `RATE_LIMIT_AUTH_VERIFY` (default `20`/min/IP), `RATE_LIMIT_TRUSTED_PROXIES`, `MULTICA_TRUSTED_PROXIES`. The `RATE_LIMIT_*` variables only take effect once `REDIS_URL` is set, and the limiter fails open (does not block sign-ins) if Redis becomes temporarily unavailable. **External integrations:** GitHub (`GITHUB_APP_SLUG`, `GITHUB_WEBHOOK_SECRET`, `GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY` — without the App ID and key, PRs still link/mirror/trigger merge-to-done, but cards show no CI/mergeability status and "pick from GitHub" is disabled), Lark (`MULTICA_LARK_SECRET_KEY`), Slack (`MULTICA_SLACK_SECRET_KEY`), Composio (`COMPOSIO_API_KEY`, `COMPOSIO_CALLBACK_BASE_URL`, `COMPOSIO_STATE_SECRET`), self-hosted Git — Forgejo/Gitea/GitLab (`MULTICA_VCS_INTEGRATION_ENABLED`, `MULTICA_VCS_SECRET_KEY` — a base64-encoded 32-byte key generated via `openssl rand -base64 32`; the feature is entirely unavailable without it). **Server-side LLM** (`MULTICA_LLM_API_KEY`, `MULTICA_LLM_BASE_URL`, `MULTICA_LLM_DEFAULT_MODEL` default `gpt-5.6-luna`) is a separate concern from AI coding tool credentials: it only powers server-side assist generation such as conversation titles. With both key and base URL empty, this generation is off and callers use local fallback logic. **Daemon configuration** is read on the computer running agents, not in the API container: `MULTICA_SERVER_URL` (default `ws://localhost:8080/ws`), `MULTICA_DAEMON_DEVICE_NAME` (default hostname), `MULTICA_AGENT_RUNTIME_NAME` (default `Local Agent`), `MULTICA_DAEMON_POLL_INTERVAL` (default `30s`), `MULTICA_DAEMON_HEARTBEAT_INTERVAL` (default `15s`), `MULTICA_DAEMON_MAX_CONCURRENT_TASKS` (default `20`), `MULTICA_AGENT_TIMEOUT` (default `0`, no limit), `MULTICA_AGENT_IDLE_WATCHDOG` (default `30m`), `MULTICA_AGENT_TOOL_WATCHDOG` (default `2h`), `MULTICA_OPENCODE_IDLE_WATCHDOG` (default `10m`), `MULTICA_CODEX_SEMANTIC_INACTIVITY_TIMEOUT` (default `10m`), `MULTICA_CODEX_HANDSHAKE_TIMEOUT` (default `30s`), `MULTICA_DAEMON_AUTO_UPDATE` (Cloud default `true`; self-hosted default `false`), `MULTICA_DAEMON_AUTO_UPDATE_INTERVAL` (default `6h`), `MULTICA_DAEMON_AUTO_RELOAD` (default `true`; restarts into a binary replaced on disk out of band — independent of auto-update), `MULTICA_WORKSPACES_ROOT` (default `~/multica_workspaces`), `MULTICA_KEEP_ENV_AFTER_TASK` (default `false`). Each AI coding tool also accepts `MULTICA_<PROVIDER>_PATH` and `MULTICA_<PROVIDER>_MODEL`; `MULTICA_<PROVIDER>_ARGS` for machine-wide default arguments is currently supported for five tools (Claude Code, Codex, CodeBuddy, Qwen Code, QwenPaw), e.g.: ```dotenv MULTICA_CLAUDE_PATH=/opt/bin/claude MULTICA_CLAUDE_ARGS=--max-turns 40 ``` QwenPaw has no `MULTICA_QWENPAW_MODEL` because Multica never sends it a model. Precedence overall: command-line flag → environment variable → `~/.multica/config.json` → built-in default. Daemon settings can persist to `~/.multica/config.json` (or `~/.multica/profiles/<name>/config.json`) instead of shell env vars: ```bash multica config set poll_interval 10s multica config show ``` Supported keys mirror the env vars above (`server_url`, `app_url`, `workspace_id`, `device_name`, `runtime_name`, `max_concurrent_tasks`, `poll_interval`, `heartbeat_interval`, `agent_timeout`, `codex_semantic_inactivity_timeout`, `codex_handshake_timeout`, `disable_auto_update`, `auto_update_check_interval`, `disable_auto_reload`). Duration keys reject `0s`/negative values except `agent_timeout`, where `0s` explicitly disables the run time limit; an empty string clears a persisted value back to the env var or default; `max_concurrent_tasks` requires a non-negative integer. **Observability:** `ANALYTICS_DISABLED` (default `false`), `POSTHOG_API_KEY` (reporting off when unset), `POSTHOG_HOST` (default `https://us.i.posthog.com`), `METRICS_ADDR` (empty by default — not started; see [[concepts/security-model]]-adjacent guidance to bind it privately), `REALTIME_METRICS_TOKEN`. ### Project resources A project's **resources** tell agents which code a body of work uses and where to run; they stay linked to the project so URLs/paths aren't re-pasted per issue. Two resource types: | Resource | Best for | Where runs happen | |---|---|---| | GitHub repository | Code shared by the team, checkouts managed by the runtime | A runtime-managed working directory | | Local directory | An existing checkout, a very large repo, or inspecting local changes directly | The original directory on a specific computer | When an agent works an issue inside the project, Multica adds the project name, description, and resource list to the run's context and writes `.multica/project/resources.json` into the working directory. The workspace's linked repository list is always included; repositories linked to the *project* additionally specify the code and default ref for that body of work. A local directory only applies to the daemon it's bound to — other computers keep using the project's GitHub repositories or the workspace repositories. **GitHub repositories:** add under the project's "Add resource," pick a workspace-linked repo, or paste a Git URL — any Git URL the runtime can reach works, not just GitHub. Self-hosted instances can connect self-hosted Forgejo, Gitea, or GitLab under **Settings → Integrations → Git hosting**. A resource's `ref` sets the default branch/tag/commit for later checkouts; `default_branch_hint` only hints a default branch and does not force a switch. **Local directories** are a Desktop-only, escape-hatch feature — "not a more convenient default." The canonical case is a checkout too large to re-clone per task (e.g. tens of gigabytes). Choosing `github_repo` instead runs in worktree mode by default, giving unlimited concurrency on the same repo; choosing `local_directory` means every task on that folder runs **strictly one at a time, forever**. The path must be absolute, already exist, and be readable/writable by the current daemon; system roots, drive roots, home directories and their parents, and system directories (`/etc`, `/var`, `/tmp`, `/usr`, `/opt`) are all rejected, and symlinks are resolved to their real path and re-validated (the serial lock applies to the real path too). Each project can link at most one local directory per daemon; different team computers can each link their own directory for the same project. A local directory is **not** an isolated environment — the agent directly sees and modifies the current branch and uncommitted files; Multica does not auto-switch branches, stash, commit, push, or open PRs on its own. **Serialization:** when two tasks target the same real directory, the later one enters `waiting_local_directory` and resumes once the earlier one releases the directory (two paths reaching the same directory via different symlinks serialize identically). Waiting doesn't modify the directory; a waiting task can be cancelled, or it just waits. To work on several changes at once, use a GitHub repository resource instead so the runtime prepares a separate working directory per task. **What gets written during a run:** beyond code changes, the runtime may write instruction files the current AI coding tool needs plus `.multica/project/resources.json` — add these to `.gitignore` if undesired in version control. Multica never deletes a linked local directory during environment cleanup; changes there need the same review as running an AI coding tool in your own terminal. **CLI management:** ```bash # Link a repository when creating a project multica project create \ --title "Agent UX" \ --repo https://github.com/multica-ai/multica # List and add resources multica project resource list <project-id> multica project resource add <project-id> \ --type github_repo \ --url https://github.com/multica-ai/multica \ --ref main # Link a local directory on a specific daemon multica project resource add <project-id> \ --type local_directory \ --local-path /absolute/path/to/repo \ --daemon-id <daemon-id> # Remove a resource multica project resource remove <project-id> <resource-id> ``` Resource changes affect only tasks created afterward — they do not rewrite records of runs that already ended. ## Key Parameters - Restart discipline: every env var change needs a process restart; `docker compose restart` doesn't re-read `.env`, `up -d` does. - `FRONTEND_ORIGIN` is the single most load-bearing self-host variable — CORS, cookies, invitation links, and WebSocket origin checks all key off it. - `AUTH_TOKEN_TTL` default `720h`; `MULTICA_DAEMON_MAX_CONCURRENT_TASKS` default `20`; agent-level concurrency default of 6 tasks is documented separately in [[concepts/troubleshooting]]. - `MULTICA_WORKSPACES_ROOT` default `~/multica_workspaces` — root for per-task working directories. - Project resource types: `github_repo` (worktree mode, unlimited concurrency) vs. `local_directory` (Desktop-only, one project ↔ one directory per daemon, strictly serial execution). - Config precedence (daemon-side): CLI flag → environment variable → `~/.multica/config.json` → built-in default. ## When To Use Consult the environment-variable reference whenever configuring or debugging a self-hosted deployment (paired with [[concepts/self-hosting]] for the deployment steps themselves and [[concepts/auth-and-tokens]] for the auth-specific subset). Use project resources to bind a project to its code once, instead of re-pasting a repo URL into every issue; reach for `local_directory` only when `github_repo`'s worktree model genuinely doesn't fit (huge repo, need to inspect local changes directly) — otherwise the serialization cost is usually not worth it. ## Risks & Pitfalls - Setting `DISABLE_WORKSPACE_CREATION=true` has no owner/admin exception — it blocks every user, full stop. - `RATE_LIMIT_*` variables are silently inert without `REDIS_URL` set — a startup log line is the only signal that rate limiting is off. - Without `GITHUB_APP_ID`/`GITHUB_APP_PRIVATE_KEY`, GitHub PRs still function but silently lose CI/mergeability display — easy to miss since nothing errors. - `local_directory` project resources serialize **all** tasks on that folder — a team that reaches for this as a convenience default (instead of `github_repo`) will unexpectedly queue agents that could otherwise run in parallel. - Rejected local-directory paths (home directories, their parents, system directories) fail validation even through a symlink that resolves to one of them — don't expect a symlink to bypass the restriction. - Server-side LLM variables (`MULTICA_LLM_*`) are easy to confuse with AI coding tool credentials — they only affect assist features like conversation titles, not what an agent uses to do the actual coding work. ## Related Concepts - [[concepts/self-hosting]] — the deployment workflow these variables are set within. - [[concepts/auth-and-tokens]] — the auth-specific subset of these variables in full detail. - [[concepts/security-model]] — `MULTICA_WORKSPACES_ROOT` and daemon-side isolation context. - [[concepts/troubleshooting]] — symptoms produced by common misconfiguration of these variables. ## Sources - raw/github_doc-apps-docs-content-docs-environment-variables-mdx.md - raw/github_doc-apps-docs-content-docs-project-resources-mdx.md <!-- ===== multica/wiki/concepts/core-concepts.md ===== --> --- title: "Core Concepts" type: concept tags: [overview, board, agents, foundational, user, well-established] created: 2026-08-10 updated: 2026-08-10 sources: ["raw/github_doc-apps-docs-content-docs-concepts-mdx.md"] confidence: high multica_version: "v0.4.22" --- ## Definition Multica's domain model is built from a small set of primitives that all relate back to a single container, the workspace. The docs group them as "basic objects" (Workspace, Issue, Project), "agents and execution" (Agent, Skill, Runtime, Task), and "collaboration and automation" (Squad, Chat, Inbox, Autopilot) (raw/github_doc-apps-docs-content-docs-concepts-mdx.md). ## How It Works - **Workspace** — the self-contained scope where a team works; all work and configuration happen inside it, and humans and agents collaborate in the same workspace. See [[concepts/board-and-work-items]]. - **Issue** — a piece of work plus the description, discussion, status, and history that accumulate around it; the basic unit of day-to-day work. Its assignee can be a member, an agent, or a squad. See [[concepts/board-and-work-items]]. - **Project** — organizes related issues under one goal, tracks overall progress, and can bind resources such as repositories and directories for execution. See [[concepts/board-and-work-items]]. - **Agent** — an AI collaborator in the workspace: a reusable configuration of name, instructions, model, skills, Access, and runtime. An agent is not a long-running process; it executes only when triggered. - **Skill** — a reusable capability package; instructions define who an agent is, a skill describes how a kind of work is done, and a skill can be attached to multiple agents. See [[concepts/skills]]. - **Runtime** — where execution actually happens: a computer connected to Multica plus the AI coding tools on it. The agent is the identity; the runtime is the computer that executes it. - **Task** — one concrete execution record for an agent. Every trigger produces a task, which a runtime completes before writing results back to the issue. One issue can produce multiple tasks over time, and a finished run does not mean the issue is done. - **Squad** — a group of agents and members led by an agent leader; assigning an issue to a squad has the leader coordinate the work. See [[concepts/squads]]. - **Chat** — a way to talk that is not attached to an issue, good for questions and quick experiments; each message triggers one run. - **Inbox** — a member's notification center: activity on subscribed issues, mentions, and assignments land here. Agents do not use the inbox. - **Autopilot** — triggers agent runs automatically on a schedule or from external events; can also be run manually. See [[concepts/autopilots]]. ## Key Parameters How the objects relate, end to end (raw/github_doc-apps-docs-content-docs-concepts-mdx.md): - The **workspace** is the container for everything; humans and **agents** collaborate inside it. - An **issue** records a piece of work; related issues are organized with **projects**. - Assigning, @-mentioning, **chat**, or an **Autopilot** triggers an agent, producing a **task**. - The task completes on a **runtime**, and the results are written back to where it was triggered. - **Skills** let what works be reused across agents; **squads** let multiple agents work together. - Every notification for humans along the way goes to the **inbox**. ## When To Use Use this page as the map before diving into any single primitive's docs — it is the fastest way to see how workspaces, issues, projects, agents, skills, runtimes, tasks, squads, chat, inbox, and autopilots fit together before reading the full mechanics of assignment, execution, or automation. ## Risks & Pitfalls - Conflating an issue with a task is a common error: an issue is the persistent record of a piece of work, while a task is one agent run against it — a run finishing does not mean the issue is finished (raw/github_doc-apps-docs-content-docs-concepts-mdx.md). See [[concepts/board-and-work-items]]. - An agent is not a standing process — it does nothing until explicitly triggered by assignment, mention, chat, or Autopilot. - Skills and squads are easy to confuse: a skill is knowledge attached to one agent at a time; a squad is a group of agents/members coordinated by a leader. They solve different problems and are not substitutes for each other. ## Related Concepts - [[concepts/multica-overview]] — what Multica is and the teammate model these objects implement. - [[concepts/board-and-work-items]] — projects, workspaces, tasks, and issues in depth. - [[concepts/assigning-issues]] — the trigger path from issue to task to agent. - [[concepts/squads]] — the leader/member coordination model. - [[concepts/autopilots]] — the scheduled/webhook trigger model. - [[concepts/skills]] — reusable agent know-how. - [[concepts/getting-started]] — put these objects to work in five minutes. ## Sources - raw/github_doc-apps-docs-content-docs-concepts-mdx.md <!-- ===== multica/wiki/concepts/creating-agents.md ===== --> --- title: "Creating and Configuring an Agent" type: concept tags: [agents, workflow, foundational, user, operator] multica_version: "v0.4.22" created: 2026-08-10 updated: 2026-08-10 sources: ["raw/github_doc-apps-docs-content-docs-agents-create-mdx.md"] confidence: high --- ## Definition Creating an agent is the process, on a workspace's **Agents** page (click **New agent**), of turning the [[concepts/agents]] identity model into a concrete, runnable configuration: a name, a bound runtime, instructions, optional skills, a model/thinking-level choice, an Access setting, and execution settings. It requires a working [[concepts/providers-and-runtimes]] runtime to exist first — the runtime decides which computer and AI coding tool the agent uses, while the agent holds the long-lived identity, instructions, and capabilities. ## How It Works **Starting points.** The creation page offers two options: | Option | When it fits | |---|---| | Start blank | You already know the agent's responsibilities and want to fill in every field yourself. | | Build with AI | Describe the goal first and let the Agent Builder ask the key questions and generate a draft. | Build with AI needs an online runtime for the Builder conversation itself. Either way, the final configuration can be reviewed and edited before creation. **Required fields.** Only two things are mandatory: - **Name** — must be unique within the workspace. - **Runtime** — the environment that actually executes tasks. Everything else can start at its default and be adjusted later. By default, only the creator can run a newly created agent. **Description vs. instructions.** The description is a short, display-only introduction shown in the agent list and detail page — it never enters the AI coding tool's prompt. Instructions, by contrast, are provided to the agent on every run and typically cover: what it is/isn't responsible for, what to check first, what it may modify, how to deliver results, and when to check with a member before proceeding. Example from the docs: ```text You review frontend pull requests. Read the diff and related tests first, and check only: - React and TypeScript correctness - Accessibility - Consistency with existing component patterns Do not modify code directly. Post findings in an issue comment, ordered by severity; when nothing blocks, state clearly that the change can merge. ``` **Skills.** During creation you can pick one or more [[concepts/skills]] (planned page) from the workspace. Skills suit methods and material reused *across* agents; requirements specific to one agent belong in its instructions instead. **Runtime, model, and thinking level.** Each runtime already maps to one AI coding tool. After picking a runtime, you can pick a model and thinking level the tool supports (some tools, like Codex, also offer a service tier): - Left blank, the runtime or local CLI default applies. - With a model set, the agent uses that override for tasks it picks up afterward. - Some runtimes manage models themselves, so no model picker is shown at all. Tools differ in supported models, session resume, skills, and MCP capabilities — see [[entities/supported-agents-catalog]]. **Access.** Decides which members can run this agent (assign, @-mention, or chat): | Access | Meaning | |---|---| | Only me | Only you can run it (the default). | | Entire workspace | Every workspace member can run it. | | Specific people | Only you and the selected members can run it. | Only the agent owner can change Access — workspace admins cannot. Admins can manage the rest of the configuration but cannot use their admin role to run agents they aren't granted. **Configuration after creation.** On the agent's detail page, you can keep adjusting: | Setting | What it does | |---|---| | Concurrency limit | How many tasks the agent runs at once. Default is 6; tasks beyond the cap keep queuing. | | Environment variables | Injected when the AI coding tool starts. | | Custom arguments | Appended item by item to the AI coding tool's CLI arguments. | | MCP | MCP server configuration for tools that support it. | | Integrations | External services this agent can use. | The daemon hosting the runtime also has a global concurrency cap (default 20); the effective concurrency is the *smaller* of the agent's cap and the daemon's cap. Editing configuration never changes tasks already running — later tasks use whatever configuration was saved when the runtime picked them up. **Environment variables and credentials.** These suit limited-privilege credentials (e.g. a read-only API key or single-scope token) needed at run time. `custom_env` values are stored **in plaintext in the Multica server database** — this is not "stays on this machine" data. Agent list/detail endpoints return only an opaque count, never the values; only workspace `owner`s and `admin`s can unlock and modify values, and every read or change leaves an audit record. A running agent cannot call admin endpoints to read another agent's variables. Do not use production database admin passwords or other high-value long-lived credentials. Critical runtime variables (`PATH`, `HOME`, `MULTICA_*`) cannot be overridden here. **Custom arguments and MCP.** Custom arguments are passed to the AI coding tool as an array, item by item, without shell expansion — validity is up to the tool itself, and settings with a dedicated field elsewhere don't need to be repeated here. MCP configuration may contain tokens and follows the same storage/display rules as environment variables. Only runtimes that support managed MCP configuration show this section at all. **Duplicating an agent.** Duplication carries over most working configuration except the name — instructions, skills, custom arguments, avatar, concurrency limit, and Access settings, plus model, thinking level, and service tier. If the original runtime is unavailable and the copy is forced onto another runtime, the model/thinking level/service tier are cleared and must be reselected. Environment variable values and MCP configuration are never copied. Duplication keeps the original agent's runtime binding and Access settings. **Creating with the CLI:** ```bash multica agent create \ --name "Frontend Reviewer" \ --runtime-id <runtime-id> \ --description "Reviews frontend pull requests" \ --instructions "Read the diff and tests first; post review conclusions only as issue comments." ``` Plaintext in command-line arguments ends up in shell history; stdin and permission-restricted files do not. To copy an existing, similarly configured agent instead: ```bash multica agent copy <agent-id> ``` By default the copy stays on the same runtime; add `--runtime-id` to move it (which also requires `--model`). Environment variables, MCP configuration, and `runtime_config` are never copied; the runtime binding itself is kept. ## Key Parameters - **Name** (unique per workspace) and **Runtime** — the only two required fields. - **Concurrency limit** — default 6 per agent; effective cap is `min(agent limit, daemon global cap)` (daemon default 20). - **Access** — `Only me` (default), `Entire workspace`, `Specific people`; changeable only by the owner. - **Model / thinking level / service tier** — tool-dependent; some tools hide the picker entirely. - **Environment variables and MCP** — server-stored, plaintext, owner/admin-gated, audit-logged, never copied on duplication. ## When To Use - Use **Start blank** when the agent's responsibilities are already clear. - Use **Build with AI** when you'd rather describe a goal and let the Builder draft the configuration (requires an online runtime). - **Duplicate** an existing agent when a similarly configured one already exists, rather than rebuilding from scratch — then re-set environment variables, MCP, and (if forced to a new runtime) model settings. - Use environment variables only for limited-privilege, single-purpose credentials — not long-lived high-value secrets. ## Risks & Pitfalls - `custom_env` values live in plaintext in the server database — treat them as visible to any owner/admin with unlock access, not as machine-local secrets. - CLI-supplied instructions/descriptions containing sensitive text land in shell history; prefer stdin or permission-restricted files for anything sensitive. - Editing an agent's configuration does not affect tasks already running — don't expect an instruction change to alter an in-flight run. - Duplicating an agent silently drops environment variables and MCP configuration, and may drop model/thinking-level/service-tier choices if forced onto a new runtime. - Critical variables (`PATH`, `HOME`, `MULTICA_*`) cannot be overridden via agent environment variables — attempts to do so will not take effect. ## Related Concepts - [[concepts/agents]] — the identity/lifecycle model this configuration process fills in. - [[concepts/providers-and-runtimes]] — the runtime prerequisite, and how tool capability differences (models, MCP, skills) feed the choices made here. - [[concepts/triggering-and-mentioning-agents]] — what happens once a configured agent is put to work. - [[entities/supported-agents-catalog]] — per-tool differences that affect model/MCP/skill choices while configuring. - [[concepts/skills]] (planned) — the reusable material bound to an agent at creation time. - [[concepts/assigning-issues]] (planned) — validating a freshly created agent with real work. - [[concepts/cli-and-daemon]] (planned) — the fuller CLI reference behind `multica agent create`/`copy`. - [[concepts/security-model]] (planned) — the broader credential and access-control picture. ## Sources - raw/github_doc-apps-docs-content-docs-agents-create-mdx.md <!-- ===== multica/wiki/concepts/desktop-and-mobile-apps.md ===== --> --- title: "Desktop and Mobile Apps" type: concept tags: [clients, cli] created: 2026-08-10 updated: 2026-08-10 sources: ["raw/github_doc-apps-docs-content-docs-desktop-app-mdx.md", "raw/github_doc-apps-docs-content-docs-mobile-app-mdx.md"] confidence: high multica_version: "v0.4.22" --- ## Definition Multica ships two native client apps beyond the web app: **Desktop** (macOS, Windows, Linux), which bundles and manages its own agent daemon automatically, and a **Mobile** client (iOS only — no Android yet, and not on the App Store) that must currently be built from source on a Mac and side-loaded. Both use the same account and workspace data as the web app; nothing needs manual syncing between them. ## How It Works **Desktop.** Install the `.dmg` (macOS), `.exe` (Windows), or `.AppImage`/`.deb`/`.rpm` (Linux) from the [downloads page](https://multica.ai/download), then sign in with the same email used on the web. Compared to web, Desktop keeps a **separate set of tabs per workspace** (switching workspaces swaps in that workspace's own saved tabs, reordering/pinning/closing and forward-back history all persist per tab), and it **starts its own bundled daemon automatically** after sign-in — no `multica daemon start` needed. That bundled CLI only serves the app's managed runtime; running `multica issue ...` etc. in a terminal still requires installing the CLI separately (see [[concepts/cli-and-daemon]]). Desktop creates a dedicated CLI profile per Multica service at `~/.multica/profiles/desktop-<host>/`; it never reads or overwrites the terminal's default profile, and a separately, manually started daemon shows up as its own distinct runtime. Logging out clears every tab saved on that machine. Auto-update is on by default (checks and downloads in the background; restart to install immediately or let it install on next quit; toggle under **Settings → Updates**); update feeds are split by OS/architecture (Windows arm64 and macOS x64/Intel each get a dedicated feed, everything else uses the default feed, chosen automatically) — Linux auto-update only works for `.AppImage`, `.deb`/`.rpm` need a fresh package install over the old one. To point Desktop at a **self-hosted instance** instead of Cloud (the default), create `desktop.json` in the home directory's `.multica` folder (`~/.multica/desktop.json` on macOS/Linux, `C:\Users\<you>\.multica\desktop.json` on Windows) with at minimum: ```json { "schemaVersion": 1, "apiUrl": "https://api.example.com" } ``` `apiUrl` is required (`http`/`https`); `wsUrl` and `appUrl` are derived automatically if omitted (`wsUrl` swaps scheme to `ws`/`wss` and appends `/ws`; `appUrl` strips a leading `api.` when the host has three-plus labels) — override them explicitly only when the web app, API, and WebSocket live on genuinely different domains or the host doesn't fit the prefix-stripping convention. This file is **not** the CLI's `~/.multica/config.json` and the keys differ (`apiUrl` vs. `server_url`); Desktop never reads the CLI config. It is read once at startup, so restart Desktop after saving. A missing file silently falls back to Cloud with no error; an invalid one shows a configuration error and does not fall back — the fastest way to tell the two failure modes apart. On Windows, watch for Notepad silently appending `.txt` (verify with `Get-ChildItem "$env:USERPROFILE\.multica" -Filter "desktop.json*"`) and PowerShell redirection producing UTF-16/BOM output that fails to parse; writing via `[System.IO.File]::WriteAllText(...)` from PowerShell avoids both. A known Windows false positive: Defender may quarantine the bundled CLI (`...\app.asar.unpacked\resources\bin\multica.exe`) as `Trojan:Script/Wacatac.B!ml` — the `!ml` suffix means a heuristic verdict, not a signature match, triggered because the binary is unsigned and opens network connections / starts background processes. Verify the release artifact's SHA-256 against the release's published `checksums.txt` before restoring the quarantined file and adding exclusions for `%LOCALAPPDATA%\Programs\@multicadesktop` and `%APPDATA%\Multica` (both matter — a missing bundled CLI gets re-downloaded into the second path). **Mobile (iOS).** There is no packaged install yet — building requires a Mac with Xcode, an Apple ID under Xcode → Settings → Accounts, an iPhone with Developer Mode enabled, and Node.js/pnpm/Git. The flow is: ```bash git clone https://github.com/multica-ai/multica.git cd multica pnpm install pnpm ios:mobile:device:prod:release ``` This produces a Metro-independent Release build installed directly on the connected iPhone (trust the developer certificate under Settings → General → VPN & Device Management if it's blocked from opening). Apps signed with a **free** Apple ID only run for **7 days**, after which reconnecting the iPhone and re-running the same build command re-signs it; an Apple Developer Program account signs for longer and also enables TestFlight/regular distribution — either way, server-side data (workspaces, issues, comments, run history) is never lost by reinstalling or re-signing, since it all lives on the server. A `No matching provisioning profiles found` error means the default bundle identifier doesn't belong to your Apple ID — set `EXPO_BUNDLE_IDENTIFIER_PROD=com.yourname.multica` (any reverse-domain name your Apple Developer team owns; it has no effect on the Multica account) and rebuild. Updating is manual: `git pull --ff-only && pnpm install && pnpm ios:mobile:device:prod:release` — there is no auto-update. To connect Mobile to a **self-hosted instance**, edit `apps/mobile/.env.production` before building: ```dotenv EXPO_PUBLIC_API_URL=https://api.example.com EXPO_PUBLIC_WEB_URL=https://app.example.com ``` `EXPO_PUBLIC_API_URL` is required; `EXPO_PUBLIC_WEB_URL` is optional and only powers "Copy link"/"Open on web" menu items (hidden when unset). Rebuild after editing. The phone must be able to reach the API address directly — a LAN address must not be `localhost`, since on-device that resolves to the phone itself. ## Key Parameters - Desktop daemon profile path: `~/.multica/profiles/desktop-<host>/` — separate from the terminal's default CLI profile. - `desktop.json` location and required key `apiUrl`; optional `wsUrl`, `appUrl` with documented auto-derivation rules; `schemaVersion: 1`. - Desktop update feeds split by OS/architecture; Linux auto-update limited to `.AppImage`. - iOS free-signing validity window: 7 days. - Mobile self-host config: `EXPO_PUBLIC_API_URL` (required), `EXPO_PUBLIC_WEB_URL` (optional) in `apps/mobile/.env.production`. - `EXPO_BUNDLE_IDENTIFIER_PROD` — override for provisioning-profile mismatches. ## When To Use - Use **Desktop** when you want the daemon managed automatically (no separate `multica daemon start`) and per-workspace tab persistence. - Use **web** for a quick look on a shared or unfamiliar computer, since it needs no install. - Build **Mobile** only if iOS access is required today and you're prepared to re-sign every 7 days on free signing, or to enroll in the Apple Developer Program for longer-lived builds. - Prefer the CLI installed separately (see [[concepts/cli-and-daemon]]) whenever terminal access to `multica issue`/`agent`/etc. is also needed alongside Desktop. ## Risks & Pitfalls - Desktop's bundled CLI only serves the app's own managed runtime — expecting `multica` commands to work in a terminal just because Desktop is installed is a common mistake; it must be installed separately. - Editing `desktop.json` incorrectly fails silently as "file not found → falls back to Cloud" versus "found but invalid → configuration error, no fallback"; misreading which failure mode you're in wastes debugging time. - Windows editors can produce a `desktop.json.txt` or wrongly-encoded file that Desktop can't read at all — verify the exact filename and use direct-write (`WriteAllText`) rather than `>` redirection or `Out-File`. - Windows Defender quarantining the bundled CLI as a false positive is expected on unsigned freshly-published Windows builds — verify the SHA-256 against `checksums.txt` before adding any exclusion, and only exclude paths matching the official install locations. - iOS builds on free signing silently stop working after 7 days with no warning beforehand — plan re-signing accordingly, or use Apple Developer Program signing for anything long-lived. - Committing an edited `apps/mobile/.env.production` writes a personal API address into the repository's production configuration. - A self-hosted deployment reached over plain HTTP or without WebSocket proxying blocks Desktop from connecting at all — see [[concepts/self-hosting]] for the access requirements. ## Related Concepts - [[concepts/cli-and-daemon]] — the daemon Desktop manages automatically, and the CLI installed separately for terminal use. - [[concepts/self-hosting]] - [[concepts/troubleshooting]] ## Sources - raw/github_doc-apps-docs-content-docs-desktop-app-mdx.md - raw/github_doc-apps-docs-content-docs-mobile-app-mdx.md <!-- ===== multica/wiki/concepts/getting-started.md ===== --> --- title: "Getting Started" type: concept tags: [overview, board, agents, foundational, user, well-established] created: 2026-08-10 updated: 2026-08-10 sources: ["raw/github_doc-apps-docs-content-docs-cloud-quickstart-mdx.md", "raw/github_doc-apps-docs-content-docs-tutorial-mdx.md"] confidence: high multica_version: "v0.4.22" --- ## Definition Getting started with Multica means connecting a computer as a runtime, creating an agent, and handing it a first issue. The [[concepts/multica-overview|docs]] describe two on-ramps: the **Quickstart**, a five-step path to one completed run, and the full **Tutorial**, which walks a personal-website project through every core flow — multiple agents, a squad, skills, and an autopilot. ## How It Works **Quickstart path** (raw/github_doc-apps-docs-content-docs-cloud-quickstart-mdx.md): 1. **Sign in and open your workspace** — on the web at multica.ai or with Multica Desktop; email verification codes and Google sign-in are both supported. 2. **Connect a computer** — Desktop registers the machine it runs on automatically and detects installed AI coding tools; on Web, or to add another computer, open **Configure → Runtimes**, click **Add a computer**, and run the two commands it shows: ```bash curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash multica setup ``` ```powershell irm https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.ps1 | iex multica setup ``` `multica setup` opens a browser to complete sign-in, then leaves the daemon running in the background. Success check: an online computer appears in the runtime list. 3. **Create an agent** — open **Workspace → Agents**, click **New agent**, and either **Start blank** (only a name is strictly required) or **Build with AI** (needs an online runtime). Success check: the agent appears in the agent list and shows online. 4. **Hand it your first issue** — click **New Issue** (or press `C`); in agent mode, set **Created by** to the new agent, describe the work in a sentence or two, and submit. Multica creates the issue, sets the agent as assignee, and starts executing immediately. 5. **Watch progress and results** — open the issue; the execution log shows run status and the agent's replies appear in the timeline. Success check: status becomes Completed and the reply appears; **View transcript** shows the full run. Common quickstart problems and first checks: no runtime found (confirm the tool is installed and runs in a terminal; **Refresh** on Desktop, rerun `multica setup` on CLI); runtime shows offline (keep Desktop open, or run `multica daemon status` / `multica daemon start`); issue stays queued (confirm the runtime is online; a runtime at its concurrency limit just keeps queueing new tasks). **Tutorial walkthrough** (raw/github_doc-apps-docs-content-docs-tutorial-mdx.md) extends this into a full working pattern using a personal-website project: 1. Create a workspace (name plus a URL slug that can't change later). 2. Connect a computer via Multica Desktop or the CLI installer. 3. Create a first agent ("Multica helper") from a blank form with explicit instructions about what it should and shouldn't touch. 4. Have that agent create a second agent ("Engineer") through chat, on a different model, scoped to building the site. 5. Have Engineer create and register a GitHub repository with `multica repo add`, then connect GitHub in **Settings → Repositories** so PRs referencing an issue link automatically. 6. File the first issue in agent mode with Engineer as creator/assignee — mixing constraints, itemized requirements, and open design latitude in one description. 7. Watch the run in the **Execution log** — Agent rows are narration, Bash/Read/Edit rows are actual tool calls. 8. Review in the issue and in **Chat** — @-reference the issue with `@`, ask about the local preview and PR status. 9. Fold recurring feedback into the agent's own instructions (the agent can self-edit with `multica agent update`) instead of repeating corrections issue by issue. 10. Add a third agent ("Reviewer") on a different tool/model, whose only job is to comment findings, never edit code; trigger it via `@Reviewer` in a comment — see [[concepts/assigning-issues]]. 11. Form a [[concepts/squads|squad]] once hand-offs (mention Reviewer, then mention Engineer) become the human's own recurring job — a leader takes over that coordination role. 12. Package a proven method as a [[concepts/skills|skill]] (e.g., a TDD method attached to Engineer, a reporting style attached to the squad leader) so it is reusable and centrally maintained. 13. Hand recurring checks to an [[concepts/autopilots|autopilot]] (e.g., a weekly code-quality pass) instead of triggering them by hand. 14. Invite other humans under **Settings → Members** — they create issues, mention agents, and join squads the same way. ## Key Parameters - **Prerequisite for both paths**: the runtime machine needs at least one supported AI coding tool already installed and signed in (Claude Code, Codex, Cursor, etc.) — Multica does not ship these tools (raw/github_doc-apps-docs-content-docs-cloud-quickstart-mdx.md, raw/github_doc-apps-docs-content-docs-tutorial-mdx.md). - **Agent mode issue creation**: selecting an agent under "Created by" generates the title automatically; a manual mode is also available for writing title and body yourself. - **Two install surfaces**: Desktop (auto-detects the local machine and its tools) vs. the CLI installer plus `multica setup` (for Web sign-in or additional machines). ## When To Use Use the Quickstart when the goal is simply to prove out one working agent run in five minutes. Use the full Tutorial when setting up a real, ongoing workspace — multiple agents with distinct roles, a review loop, a squad for coordination, skills for reuse, and an autopilot for recurring checks. ## Risks & Pitfalls - Skipping the AI coding tool installation/sign-in step on the runtime machine is the most common blocker — Multica drives the tool but never installs or authenticates it. - An issue left in `backlog` does not start a run even when assigned to an agent — it only starts once moved out of `backlog`; see [[concepts/board-and-work-items]] and [[concepts/assigning-issues]]. - Reading third-party skill content before attaching it matters: Multica does not sandbox skills, and their content is handed to the AI coding tool as-is (raw/github_doc-apps-docs-content-docs-tutorial-mdx.md). See [[concepts/skills]]. ## Related Concepts - [[concepts/multica-overview]] — what these steps are building toward. - [[concepts/core-concepts]] — the objects (workspace, issue, agent, task, runtime) referenced throughout both walkthroughs. - [[concepts/board-and-work-items]] — issues, projects, and how they organize this work afterward. - [[concepts/assigning-issues]] — the mechanics behind step 4/6 above. - [[concepts/squads]] — the coordination pattern introduced in the tutorial. - [[concepts/skills]] — packaging what an agent learns into a reusable method. - [[concepts/autopilots]] — automating the recurring check introduced at the end of the tutorial. ## Sources - raw/github_doc-apps-docs-content-docs-cloud-quickstart-mdx.md - raw/github_doc-apps-docs-content-docs-tutorial-mdx.md <!-- ===== multica/wiki/concepts/members-and-roles.md ===== --> --- title: "Members and Roles" type: concept tags: [auth, agents, user, operator, foundational, well-established] created: 2026-08-10 updated: 2026-08-10 sources: ["raw/github_doc-apps-docs-content-docs-members-roles-mdx.md"] confidence: high multica_version: "v0.4.22" --- ## Definition Every person who joins a Multica workspace is a **member**, and each member holds exactly one role: `owner`, `admin`, or `member`. Roles govern workspace settings and team management only — everyday collaboration such as creating issues and writing comments is open to all members regardless of role (raw/github_doc-apps-docs-content-docs-members-roles-mdx.md). ## How It Works **The three roles.** All roles can view the workspace and collaborate day to day. `owner` and `admin` can additionally change workspace settings and invite/change/remove `admin` or `member` accounts. Only an `owner` can grant, revoke, or remove the `owner` role itself, and only an `owner` can delete the workspace. A workspace must always keep at least one `owner`: the last remaining owner cannot be demoted, removed, or leave. **Inviting members.** An `owner` or `admin` sends invitations from **Settings → Members** by entering an email and picking a role; invitations can only grant `admin` or `member` directly — a new `owner` must first join as `admin`/`member` and then be promoted by an existing owner. The invitee accepts simply by logging in with the invited email (no prior signup step). Invitations are valid for 7 days and must be resent after expiry. The invitation link exists only inside the email itself — there is no in-product way to view or copy it — so if the email fails to send, the fix is to revoke the invitation record and send a new one. On self-hosted instances that restrict signup, an invitee without an existing account is still subject to the signup allowlist rules (`ALLOWED_EMAILS` / `ALLOWED_EMAIL_DOMAINS` / `ALLOW_SIGNUP`) when they register — see [[concepts/auth-and-tokens]]. **Changing roles.** An `admin` can move a member between `admin` and `member`, and can remove members holding either of those two roles. Any change that involves `owner` — promoting someone to owner, changing an owner's role, or removing an owner — can only be performed by an existing `owner`. Role changes take effect immediately. **Removing a member.** A removed member loses workspace access immediately, but issues, comments, and other collaboration records they created remain in the workspace. Removal also cascades: it deactivates runtimes the member owned, archives agents bound to them, cancels their unfinished tasks, and clears any grants the member had received in agent Access scopes — those grants are not automatically restored if the person rejoins later. ## Key Parameters - Three roles: `owner`, `admin`, `member` — a strict permission ladder for workspace administration only. - Invitation validity: 7 days, then must be resent. - Invitations can grant `admin` or `member` directly; `owner` requires a post-join promotion by an existing owner. - At least one `owner` must always exist per workspace (last owner cannot be demoted/removed/leave). - Role changes apply immediately; no propagation delay. ## When To Use Use `owner` sparingly — reserve it for whoever must be able to delete the workspace or manage ownership itself — and use `admin` for people who manage team membership and settings day to day. Because roles do **not** control which agents someone can run (see below), pair role assignment with each agent's own Access scope when you need to restrict who can trigger a specific agent. ## Risks & Pitfalls - Workspace roles are a common misconception source: `owner` and `admin` cannot bypass an agent's own Access scope to run agents they were not explicitly granted — roles and agent Access are two independent permission systems (raw/github_doc-apps-docs-content-docs-members-roles-mdx.md). See [[concepts/security-model]] and the planned [[concepts/agents]] page for Access scope. - Removing a member has irreversible side effects beyond access loss: it archives their agents, deactivates their runtimes, cancels their unfinished tasks, and clears agent Access grants they held — grants are **not** restored automatically if the person is re-invited later. - There is no in-app way to view or resend the raw invitation link — if delivery fails, the operator's only recourse is to revoke the invitation and issue a new one; combine with the email-delivery troubleshooting in [[concepts/troubleshooting]] when invitations silently don't arrive. - On signup-restricted self-hosted instances, inviting a brand-new (no-account) user is not enough by itself — their email must also satisfy `ALLOWED_EMAILS`/`ALLOWED_EMAIL_DOMAINS`, or `ALLOW_SIGNUP` must be true with no allowlist configured. ## Related Concepts - [[concepts/auth-and-tokens]] — signup restrictions that also gate invitation acceptance. - [[concepts/security-model]] — why role membership is not the same as agent-run permission. - [[concepts/configuration]] — the `DISABLE_WORKSPACE_CREATION` and signup environment variables that interact with roles at the platform level. ## Sources - raw/github_doc-apps-docs-content-docs-members-roles-mdx.md <!-- ===== multica/wiki/concepts/multica-overview.md ===== --> --- title: "Multica Overview" type: concept tags: [overview, board, agents, foundational, user, well-established] created: 2026-08-10 updated: 2026-08-10 sources: ["raw/github_doc-readme-md.md", "raw/github_doc-vision-md.md", "raw/github_doc-apps-docs-content-docs-how-multica-works-mdx.md", "raw/github_doc-apps-docs-content-docs-index-mdx.md"] confidence: high multica_version: "v0.4.22" --- ## Definition Multica is an open-source, self-hostable workspace where work is assigned to AI coding agents the way it would be assigned to a human teammate: an agent picks up an issue, reports progress, raises blockers, and hands the result back for review. Its tagline is "Agents that show up on the board." It drives 20 different agent CLIs (Claude Code, Codex, Cursor, and others) rather than shipping its own model, so switching providers is "a dropdown, not a migration" (raw/github_doc-readme-md.md). The name is a nod to Multics, the 1960s time-sharing operating system — Multica's bet is that a small team with agents "shouldn't feel small" (raw/github_doc-vision-md.md). ## How It Works At the center of Multica is the **board**: a shared workspace where human members and agents are both first-class participants. When an issue is assigned to an agent, Multica creates a task; an online runtime (a connected computer) claims that task, invokes the configured AI coding tool locally, and streams progress and results back into the issue's timeline and execution log (raw/github_doc-apps-docs-content-docs-how-multica-works-mdx.md). The full path of a run is: 1. The issue provides the context — description, discussion, and assignee. 2. Multica creates a task, which enters a queue (it waits there if no runtime is online). 3. A runtime claims the task and invokes the AI coding tool. 4. The tool executes locally against the working directory. 5. Progress, comments, and results are written back to the issue. Multica draws a strict boundary between what it records and what a connected computer executes: Multica holds workspaces, issues, comments, statuses, agent configuration, skills, and task/run records; the connected computer holds the AI coding tools, their credentials, the code directories, and actual command execution. This boundary is identical on Multica Cloud and in self-hosted deployments (raw/github_doc-apps-docs-content-docs-how-multica-works-mdx.md). Agents never start work on their own — every run is triggered explicitly, by assignment, an @-mention, a chat message, or an Autopilot. ## Key Parameters - **The teammate model** — an agent is given a name, a provider, and a runtime, and then "shows up on the board like anyone else" (raw/github_doc-readme-md.md); the assignee picker, activity timeline, and task lifecycle are built around agents as first-class teammates, not tools (raw/github_doc-vision-md.md). - **20 agent CLIs / runtimes** — Claude Code, Codex, Cursor Agent, GitHub Copilot CLI, Kimi, OpenCode, OpenClaw, Hermes, Pi, Antigravity, CodeBuddy, DevEco Code, Grok, Kiro CLI, Qoder CLI, Qoder CN, Qwen Code, QwenPaw, Reasonix, and Trae CLI (raw/github_doc-readme-md.md). - **Self-hostable, no lock-in** — Docker Compose or Helm on your own infrastructure; any Git host (GitHub, GitLab, Gitea, Forgejo); licensed under Apache License 2.0 plus additional conditions (raw/github_doc-readme-md.md). - **Architecture** — Next.js frontend, Go backend (Chi + WebSocket), PostgreSQL with pgvector, and an agent daemon that runs on the user's own machine or cloud box, next to the code (raw/github_doc-readme-md.md). - **The vision** — Multica aims to be "the system of record and action for human-agent work": people set direction and remain accountable, agents keep the work moving, and the original intent, decisions, actions, and outcomes stay connected to the same issue instead of vanishing with a chat session (raw/github_doc-vision-md.md). ## When To Use Multica fits teams already running multiple agent CLIs across separate terminal tabs who are losing time to re-explaining context and babysitting agents (raw/github_doc-readme-md.md). It suits teams that want agent work to be reviewable and auditable — landing in review rather than directly in main — and that want a single execution boundary across whichever Git host, cloud, or on-prem infrastructure they already use. ## Risks & Pitfalls - Multica does not ship agent CLIs — the runtime machine needs at least one supported agent CLI already installed and signed in; Multica only drives it (raw/github_doc-readme-md.md). - A completed task/run does not mean the issue's goal is met — issue completion depends on actual status and progress, not run completion (raw/github_doc-apps-docs-content-docs-how-multica-works-mdx.md). See [[concepts/board-and-work-items]]. - Anything saved to an agent's `custom_env` is stored on the Multica server and passed to the runtime at execution time — secrets that must never leave the local computer should not go there (raw/github_doc-apps-docs-content-docs-how-multica-works-mdx.md). ## Related Concepts - [[concepts/core-concepts]] — the full domain model these primitives fit into. - [[concepts/getting-started]] — the fastest path to a first run. - [[concepts/board-and-work-items]] — projects, workspaces, tasks, and issues in detail. - [[concepts/assigning-issues]] — the core hand-off workflow. - [[concepts/squads]] and [[concepts/autopilots]] — coordination and automation built on top of the core model. - [[concepts/skills]] — how teams package reusable agent know-how. ## Sources - raw/github_doc-readme-md.md - raw/github_doc-vision-md.md - raw/github_doc-apps-docs-content-docs-how-multica-works-mdx.md - raw/github_doc-apps-docs-content-docs-index-mdx.md <!-- ===== multica/wiki/concepts/providers-and-runtimes.md ===== --> --- title: "Providers and Runtimes" type: concept tags: [providers, agents, self-hosting, foundational, operator] multica_version: "v0.4.22" created: 2026-08-10 updated: 2026-08-10 sources: ["raw/github_doc-apps-docs-content-docs-providers-mdx.md", "raw/github_doc-apps-docs-content-docs-install-agent-runtime-mdx.md", "raw/github_doc-apps-docs-content-docs-daemon-runtimes-mdx.md"] confidence: high --- ## Definition The provider system is how Multica turns an already-installed, already-signed-in AI coding tool CLI on someone's computer into something an [[concepts/agents]] can be bound to and executed on. It has three layers: the **daemon** (the Multica background process on one computer), the **runtime** (one concrete execution environment — one computer plus one AI coding tool, or a custom profile), and the **provider/tool comparison** (which of the ~20 supported CLIs a given runtime wraps, and what that tool can and can't do). Multica does not replace or ship the AI coding tool — it invokes the one already installed and signed in on the machine, then writes progress and results back to the issue. The full tool catalog is in [[entities/supported-agents-catalog]]. ## How It Works **Daemon vs. runtime.** The daemon is the Multica background process running on one computer: it connects to the server, discovers local tools, claims tasks, and reports results back. A runtime is one concrete execution environment available to a workspace — one computer plus one AI coding tool (or one custom runtime profile) on that computer. Example: a computer with both Claude Code and Codex installed, connected to two workspaces, causes the daemon to register a Claude Code runtime and a Codex runtime *for each workspace*. Restarting the daemon updates existing runtime records rather than duplicating them. **Execution location and data boundaries.** The AI coding tools a local runtime invokes, those tools' own login credentials, and local code directories all stay on the connected computer — the Multica server never executes commands on behalf of local tools and does not automatically upload the entire working directory. To let the team collaborate, the server does store issues, comments, agent configuration, task context, run records, and whatever an agent writes back (which can include code snippets it chose to include). An agent's custom environment variables and MCP configuration, however, are stored server-side and sent to the runtime at execution time — "local execution" does not mean every secret lives only on the local machine (see [[concepts/creating-agents]]#environment-variables-and-credentials). **Choosing and installing a tool.** A tool already installed and signed in needs no extra setup. Otherwise, the install flow is: 1. **Choose a tool** from the supported list (see [[entities/supported-agents-catalog]] for the full table and install-guide links). "Supported" means Multica can invoke the CLI — it does not mean Multica provides the tool's account, subscription, or model quota. 2. **Sign in on the machine** — launch the tool once in its own terminal and complete its sign-in/model-provider setup; if it can't complete requests there, daemon invocations fail the same way. Reasonix additionally needs `reasonix setup` with a default provider/model configured first. QwenPaw's provider/model must be chosen in QwenPaw's own configuration — Multica cannot override it. These login credentials stay local to the tool; Multica never receives login tokens from Claude, Codex, Cursor, or any other CLI. Minimum versions: Claude Code 2.0.0+, Codex 0.100.0+, Copilot 1.0.0+, Grok 0.2.89+, Qwen Code 0.20.0+. Below the minimum, the daemon does not register the runtime. 3. **Confirm the daemon can find the command** — `command -v <command> && <command> --version` (macOS/Linux/WSL) or `Get-Command <command>` (Windows PowerShell). If the terminal finds the tool but Desktop/the daemon does not, they're likely using different `PATH` values; restart the app, or set an absolute path via the matching `MULTICA_<PROVIDER>_PATH` environment variable. 4. **Re-detect and confirm online** — `multica daemon start`, or `multica daemon restart` if already running (Desktop: quit and reopen). The **Runtimes** page should then show the tool as online under the target computer, ready to be selected when creating/editing an agent. If no tools are detected: run the tool directly to confirm install/sign-in, check the exact command/path, run `multica daemon logs -f` for version/path/auth errors, restart the daemon, and recheck the Runtimes page. **Starting and operating the daemon.** With Multica Desktop, the app starts the daemon automatically. On the web, a remote computer, or headless environments, install the Multica CLI and run `multica daemon start`. Common commands: | Command | Purpose | | --- | --- | | `multica daemon status` | Show daemon and connection status | | `multica daemon logs -f` | Follow the logs | | `multica daemon restart` | Restart the daemon and re-detect local tools | | `multica daemon stop` | Stop the daemon | | `multica daemon start --foreground` | Run in the current terminal, for debugging | On startup the daemon detects supported tools on `PATH` and registers runtimes for the workspaces it's allowed to connect to. The daemon needs at least one built-in supported CLI detected before it will even start; custom runtime profiles sync only *after* the daemon is up, so they cannot be the sole startup condition on a blank machine. **Dispatch and online status.** Once registered, a runtime keeps a persistent connection; when a task enters the queue the server notifies the matching daemon, and the daemon also polls periodically as a backstop. The daemon sends a heartbeat every 15 seconds; the server combines heartbeats and connection state to judge online status, and after an unexpected daemon exit the runtime usually shows offline within about 3 minutes at the latest. While a runtime is offline: already-queued tasks wait up to 2 hours for it to recover; tasks that were actively running fail (eligible issue/chat tasks can retry automatically); on restart the daemon re-registers its runtimes and reclaims tasks that didn't end cleanly; and a runtime offline for more than 7 days with no agents bound to it (including archived ones) is cleaned up automatically. **Concurrency limits.** One daemon executes at most 20 tasks at a time by default, and each agent at most 6 — effective concurrency is the smaller of the two. The machine-wide cap is adjustable via `MULTICA_DAEMON_MAX_CONCURRENT_TASKS`; per-agent limits are adjusted in agent settings (see [[concepts/creating-agents]]). Parallel runs compete for machine capacity, tool account quota, and the same working directory simultaneously. **Private and public runtimes.** A local runtime is private by default — only its owner and the workspace's owners/admins can create agents on it. The owner or an admin can make it public, letting other workspace members select it too; this shares machine *capacity*, not the underlying tool's login credentials. **Custom runtime profiles.** For an internal wrapper, a version-pinned executable, or fixed extra arguments on an otherwise-compatible tool, workspace owners/admins can create a custom runtime profile: open **Runtimes**, go to the target computer, click **Add custom runtime**, choose the protocol family the command is actually compatible with (one of the families Multica already supports — see [[entities/supported-agents-catalog]]), and fill in name/command/fixed arguments. The profile is shared workspace-wide, but each connected computer resolves the command on its own `PATH` independently. The command field takes an executable and arguments, not a shell script — plain arguments/quotes/backslash escapes work, but pipes, redirects, `&&`, `;`, backticks, and env-var expansion do not (put those in a wrapper script instead). Path overrides: `multica runtime profile set-path <profile-id> --path /absolute/path/to/command` / `unset-path <profile-id>`. Editing a profile only affects tasks claimed afterward; deleting only one computer's runtime instance doesn't delete the profile itself (a running daemon re-registers it). **Choosing between tools.** Four things matter when picking a provider for an agent: whether the tool is already installed on the computer, which models the account can use, whether Multica needs to configure MCP for it, and which skills the team wants to reuse. Model lists come from the runtime itself — some tools expose a fixed set of names, others reflect local configuration/account/subscription entitlements; if you don't pick a model, the tool's own default applies, and switching tools invalidates a previously chosen model name. QwenPaw is the one tool whose model picker is inert ("Managed by runtime") — an empty list there is expected, not a sign of an offline runtime. "Multica-managed MCP" means MCP servers can be defined in the agent configuration and passed to the tool before a run; Antigravity, GitHub Copilot CLI, DevEco Code, and Pi don't read agent-level MCP configuration yet, so the field isn't shown for them. All supported tools support session resumption (continuing an existing session in a later run) provided the original session still exists and a reachable runtime executes the follow-up task — Pi is the partial exception, since it stores a local session file path and so depends more on the original computer. Before a run, Multica writes an agent's bound skills into each tool's native skill path without overwriting anything already in the repo; Codex (per-task `CODEX_HOME`), Hermes (per-task `HERMES_HOME`, only when skills are bound), and OpenClaw (`skills/` under the task's working directory) isolate this per task rather than writing into a shared system location. ## Key Parameters - **Daemon heartbeat** — every 15 seconds; offline detection within ~3 minutes of an unexpected exit. - **Queued-task grace window** — up to 2 hours while a runtime is offline before those tasks are otherwise affected. - **Runtime auto-cleanup** — 7+ days offline with no bound agents (including archived). - **Concurrency caps** — daemon-wide default 20 (`MULTICA_DAEMON_MAX_CONCURRENT_TASKS`), per-agent default 6, effective = the smaller. - **Minimum tool versions** — Claude Code 2.0.0+, Codex 0.100.0+, Copilot 1.0.0+, Grok 0.2.89+, Qwen Code 0.20.0+. - **Runtime visibility** — private (default) vs. public. - **`MULTICA_<PROVIDER>_PATH`** — absolute-path override when Desktop/daemon `PATH` differs from a terminal's. ## When To Use - Install and authenticate whichever tool(s) your team already uses — Multica drives the CLI, it doesn't provide its account or quota. - Make a runtime public when teammates should be able to route agents to that machine's spare capacity, without sharing its tool logins. - Create a custom runtime profile for an internal wrapper, pinned version, or fixed extra arguments — and put anything needing shell operators into a wrapper script instead of the command field. - Set `MULTICA_<PROVIDER>_PATH` (or the daemon-wide concurrency env var) when the daemon's environment doesn't match a working terminal's. ## Risks & Pitfalls - The daemon refuses to start without at least one built-in supported CLI detected — a machine configured only with custom runtime profiles cannot bootstrap on its own. - A public runtime shares machine *capacity* only; teammates' tasks still execute under the runtime owner's already-signed-in tool account, which can surprise teams expecting per-user credentials. - Custom runtime profile commands silently fail to support shell operators (`|`, `&&`, `;`, backticks, env expansion) — this looks like a bug but is by design. - "Local execution" is not the same as "every secret stays local": an agent's custom environment variables and MCP configuration are stored server-side and only sent to the runtime at execution time. - QwenPaw's inert, empty model picker is expected behavior, not evidence the runtime is offline — don't chase it as a bug. - Below-minimum tool versions (see Key Parameters) cause the daemon to silently not register that runtime at all, rather than erroring loudly. ## Related Concepts - [[concepts/agents]] — what gets bound to a runtime once it exists. - [[concepts/creating-agents]] — where runtime, model, and MCP choices are actually applied. - [[concepts/triggering-and-mentioning-agents]] — how queued/offline runtime state shows up when work is triggered. - [[entities/supported-agents-catalog]] — the full per-tool comparison table (detected command, session resumption, MCP, skill path). - [[concepts/cli-and-daemon]] (planned) — fuller CLI reference for `multica daemon` and `multica runtime`. - [[concepts/self-hosting]] (planned) — running the daemon/server stack on your own infrastructure. - [[concepts/security-model]] (planned) — the broader boundary between server-stored and machine-local data. - [[concepts/troubleshooting]] (planned) — deeper diagnosis steps for an offline runtime. ## Sources - raw/github_doc-apps-docs-content-docs-providers-mdx.md - raw/github_doc-apps-docs-content-docs-install-agent-runtime-mdx.md - raw/github_doc-apps-docs-content-docs-daemon-runtimes-mdx.md <!-- ===== multica/wiki/concepts/security-model.md ===== --> --- title: "Security Model" type: concept tags: [security, self-hosting, operator, advanced, well-established] created: 2026-08-10 updated: 2026-08-10 sources: ["raw/github_doc-apps-docs-content-docs-security-model-mdx.md"] confidence: high multica_version: "v0.4.22" --- ## Definition Multica's security model is defined by a single fact: when an agent picks up a task, the daemon spawns an AI coding tool (Codex, Claude Code, and so on) as a child process that runs with the **full permissions of the operating-system user running the daemon**. Multica makes no filesystem-sandbox guarantee — the real isolation boundary has to be placed *around* the daemon, not expected *from* Multica itself (raw/github_doc-apps-docs-content-docs-security-model-mdx.md). ## How It Works **The boundary is the daemon's OS user.** A task can read and write every file that user can, use that user's credentials, and reach the network without restriction. This is a deliberate design choice, not an oversight: agents are asked to install dependencies, run builds, drive cloud CLIs, and use tooling that expects a normal home directory. A partial filesystem sandbox breaks that work in hard-to-diagnose ways (the tool silently reports "not logged in" or uses the wrong account) while not actually protecting the thing that matters most — it cannot stop a task from reading credentials and exfiltrating them over the network. **Recommended isolation setups**, lightest to strongest: (1) a dedicated Unix `multica` user scoped only to the repos/credentials agents need; (2) a container with only the necessary mounts and secrets; (3) a full virtual machine. Whichever is chosen, every credential reachable from that environment should be treated as a credential the agent may use — scope tokens narrowly and prefer per-purpose deploy keys over a personal SSH key. **What Multica *does* isolate** (blast-radius reduction, not a security boundary against an actively escaping task): - Per-task working directory under `~/multica_workspaces/`, so concurrent tasks don't collide on the same checkout. - Per-task agent state — Codex tasks get a task-scoped `CODEX_HOME` for config/sessions/skills, keeping per-task settings out of `~/.codex/`. - Task-scoped API tokens — the `mat_`-prefixed `MULTICA_TOKEN` handed to a task is bound to that agent and task by the server, so it cannot act as the user or as another agent (see [[concepts/auth-and-tokens]]). **What is explicitly *not* a boundary.** Multica runs agents unattended, so tool-native approval prompts are answered automatically, and the filesystem sandbox is off on the default path: Codex runs with `sandbox_mode = "danger-full-access"` and Claude Code with `--permission-mode bypassPermissions`. The one narrow exception is Windows, where a user has explicitly opted into Codex's native sandbox (`windows.sandbox = "unelevated"` or `"elevated"`) — Multica honors that and keeps `workspace-write` for those tasks, but which platform/tool/version combinations sandbox anything at all is a compatibility detail that shifts over time, so every task should be treated as unsandboxed by default. Tasks also inherit the daemon user's real `HOME` and `XDG_*` variables — this is what lets host CLIs like `gh`, `aws`, `kubectl`, and `gcloud` work inside a task exactly as in a normal shell, but it also means everything under that home is reachable. Linux previously ran Codex tasks under a `workspace-write` sandbox with a redirected per-task `HOME`; that was removed because it left host CLIs unconfigured inside tasks and, since it only restricted writes, never stopped a task from reading and exfiltrating credentials. Linux now matches the macOS and Windows default. **Checking what a task actually ran with.** The daemon logs the effective sandbox mode at warn level whenever a task starts unsandboxed: ```bash multica daemon logs --lines 200 | grep "codex sandbox" ``` To confirm the effective Codex configuration for a specific task, read the managed block inside that task's `config.toml` under its `CODEX_HOME` — the section between `# BEGIN multica-managed` and `# END multica-managed` is written by the daemon on every run. ## Key Parameters - The isolation boundary = the OS user (or container/VM) the daemon runs as — not anything Multica configures internally. - Codex default: `sandbox_mode = "danger-full-access"`; Claude Code default: `--permission-mode bypassPermissions`. - Windows-only opt-in exception: `windows.sandbox = "unelevated"` or `"elevated"` keeps `workspace-write` for Codex tasks. - Per-task working directory root: `~/multica_workspaces/` (configurable via `MULTICA_WORKSPACES_ROOT`, see [[concepts/configuration]]). - Per-task `CODEX_HOME` isolates Codex config/sessions/skills per task. - `MULTICA_TOKEN` for a run is a task-, agent-, and workspace-scoped `mat_` token, not the user's own PAT. ## When To Use Read this before running the self-host daemon under your own personal user account (see [[concepts/self-hosting]]) — the recommended pattern is always a dedicated `multica` Unix user, a container, or a VM, chosen by how strong an isolation guarantee your infrastructure needs versus how much provisioning effort you can afford. Use the `codex sandbox` log grep whenever you need to audit or prove what sandbox mode a specific run actually used, e.g. during a security review or incident investigation. ## Risks & Pitfalls - If the daemon runs as a personal user account, a task can read SSH keys, edit shell profiles, and delete documents — Multica will not stop it (raw/github_doc-apps-docs-content-docs-security-model-mdx.md). - Do not assume the coding tool's own sandbox/approval settings provide protection in Multica's unattended context — approvals are auto-answered and the filesystem sandbox is off by default on every platform except the Windows opt-in case. - Do not assume Linux still gets the old `workspace-write` + redirected-`HOME` treatment — that protection was removed because it broke host CLI usage without actually stopping credential exfiltration; Linux now behaves like macOS and Windows (unsandboxed by default). - Per-task working directories, per-task `CODEX_HOME`, and task-scoped tokens are conveniences for avoiding accidental collisions between concurrent tasks — they are explicitly *not* protection against a task that is actively trying to escape or exfiltrate data. - Treat every credential reachable from the daemon's environment (its `HOME`, its cloud CLI logins, its SSH agent) as a credential an agent may use; scope tokens and deploy keys accordingly rather than reusing broad personal credentials. ## Related Concepts - [[concepts/self-hosting]] — where the daemon is provisioned and where isolation choices (dedicated user, container, VM) are actually made. - [[concepts/auth-and-tokens]] — the task-scoped `mat_` token referenced above. - [[concepts/members-and-roles]] — why workspace role (`owner`/`admin`/`member`) is a separate axis from what a task on disk can reach. - [[concepts/configuration]] — `MULTICA_WORKSPACES_ROOT` and other daemon-side environment variables mentioned here. ## Sources - raw/github_doc-apps-docs-content-docs-security-model-mdx.md <!-- ===== multica/wiki/concepts/self-hosting.md ===== --> --- title: "Self-Hosting" type: concept tags: [self-hosting, operator, advanced, well-established] created: 2026-08-10 updated: 2026-08-10 sources: ["raw/github_doc-apps-docs-content-docs-self-host-quickstart-mdx.md", "raw/github_doc-self-hosting-md.md", "raw/github_doc-self-hosting-advanced-md.md", "raw/github_doc-self-hosting-ai-md.md"] confidence: high multica_version: "v0.4.22" --- ## Definition Self-hosting Multica means running the **Multica service** (web, API, PostgreSQL) on infrastructure you control, instead of using Multica Cloud. It has two independently deployable parts that can live on the same machine or separate ones: the **Multica service** (Docker Compose or Kubernetes) and the **Computer** — any machine running the `multica` CLI, the agent daemon, and at least one AI coding tool (raw/github_doc-apps-docs-content-docs-self-host-quickstart-mdx.md). Self-hosting replaces only the Multica Cloud part; the daemon-and-AI-coding-tool side is identical whether the service is self-hosted or Cloud. ## How It Works ### Architecture | Component | Description | Technology | |---|---|---| | Backend | REST API + WebSocket server | Go (single binary) | | Frontend | Web application | Next.js 16 | | Database | Primary data store | PostgreSQL 17 with pgvector | Each user who runs AI agents locally also installs the `multica` CLI and runs the agent daemon on their own machine (raw/github_doc-self-hosting-md.md). ### Fastest path: one-command install ```bash # 1. Install CLI + provision the self-host server curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash -s -- --with-server # 2. Configure CLI, authenticate, and start the daemon multica setup self-host ``` Windows PowerShell: ```powershell $env:MULTICA_MODE="with-server"; irm https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.ps1 | iex multica setup self-host ``` This installs the `multica` CLI, checks out the latest self-host assets, pulls the official images from GHCR, and configures everything for localhost. Open http://localhost:3000. Docker and Docker Compose must already be installed — the script checks and links to installers if missing. A CLI-only install (server already running elsewhere) is available via Homebrew: `brew install multica-ai/tap/multica` (raw/github_doc-self-hosting-md.md). ### Step-by-step (Docker Compose) Prerequisites: Docker Engine or Docker Desktop with `docker compose` working (Compose v2 — the legacy `docker-compose` v1 is **not** supported), plus Git, Make, curl, and OpenSSL. Ports `3000` and `8080` must be free (raw/github_doc-apps-docs-content-docs-self-host-quickstart-mdx.md). ```bash git clone --depth 1 https://github.com/multica-ai/multica.git cd multica make selfhost ``` On first run, `make selfhost`: (1) creates `.env` from `.env.example`; (2) generates a random `JWT_SECRET`, PostgreSQL password, and `MULTICA_VCS_SECRET_KEY`; (3) pulls the PostgreSQL, backend, and frontend images; (4) creates persistent volumes and starts the three containers; (5) waits for the backend to answer health checks. Re-running it reuses the existing `.env` and volumes and does **not** regenerate secrets. `make selfhost` pulls published images and does not build your checkout — use `make selfhost-build` to test local source; if the target GHCR tag isn't published yet, `make selfhost` now tells you to fall back to `make selfhost-build`, which uses local `multica-backend:dev` / `multica-web:dev` tags and does not overwrite the pulled `:latest` images (raw/github_doc-apps-docs-content-docs-self-host-quickstart-mdx.md; raw/github_doc-self-hosting-md.md). Confirm readiness: ```bash docker compose -f docker-compose.selfhost.yml ps curl -fsS http://localhost:8080/readyz # {"status":"ok","checks":{"db":"ok","migrations":"ok"}} ``` The backend runs database migrations on every startup before serving traffic — there is no manual migration command for the normal path. ### Access: local vs. remote Docker Compose binds `3000` and `8080` to `127.0.0.1` only — do **not** switch this to `0.0.0.0` to expose it publicly; put a reverse proxy with HTTPS in front instead. For remote access with two domains (`app.example.com`, `api.example.com`), set in `.env`: ```bash FRONTEND_ORIGIN=https://app.example.com MULTICA_APP_URL=https://app.example.com MULTICA_PUBLIC_URL=https://api.example.com ``` Then reverse-proxy with Caddy: ```text app.example.com { @ws path /ws /ws/* handle @ws { reverse_proxy 127.0.0.1:8080 { flush_interval -1 } } handle { reverse_proxy 127.0.0.1:3000 } } api.example.com { reverse_proxy 127.0.0.1:8080 { flush_interval -1 } } ``` After editing `.env`, recreate containers to pick up the change — `docker compose restart` does **not** re-read `.env`: ```bash docker compose -f docker-compose.selfhost.yml up -d curl -fsS https://api.example.com/readyz ``` ### Logging in for the first time Self-hosted deployments default to `APP_ENV=production`, so there is no fixed verification code by default. Three ways to obtain the code (raw/github_doc-self-hosting-md.md; raw/github_doc-apps-docs-content-docs-self-host-quickstart-mdx.md): 1. **Recommended for production** — configure `RESEND_API_KEY`, restart the backend; real emails are sent. 2. **No email configured** — read the code from backend logs: ```bash docker compose -f docker-compose.selfhost.yml logs backend | grep "Verification code" ``` 3. **Deterministic local/private testing** — set `APP_ENV=development` and `MULTICA_DEV_VERIFICATION_CODE=888888`; ignored whenever `APP_ENV=production`. **Never** set this on a publicly reachable instance. ### Connecting a computer (daemon) Run on the computer that will actually execute agents — not necessarily the Docker host. This is the point where the [[concepts/security-model]] applies: run the daemon as a dedicated Unix user, in a container, or in a VM, not under a personal account, since tasks run with the daemon user's full permissions. ```bash # macOS / Linux curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash ``` ```powershell # Windows PowerShell irm https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.ps1 | iex ``` ```bash # Same machine as the service multica setup self-host # Service on another machine multica setup self-host \ --server-url https://api.example.com \ --app-url https://app.example.com ``` This checks `<server-url>/health`, opens a browser to complete login, stores local credentials, and starts the daemon. Confirm with `multica daemon status` — expect `Daemon: running`, a populated `Agents` list of detected AI coding tools, and `Workspaces` greater than `0`. At least one supported AI coding tool must already be installed and signed in on the computer. The full supported list (each with its PATH binary name), per the top-level guide: Claude Code (`claude`), Antigravity CLI (`agy`), CodeBuddy Code (`codebuddy`), DevEco Code (`deveco`), Codex (`codex`), GitHub Copilot CLI (`copilot`), OpenClaw (`openclaw`), OpenCode (`opencode`), Hermes (`hermes`), Pi (`pi`), Cursor Agent (`cursor-agent`), Kimi (`kimi`), Reasonix (`reasonix`; run `reasonix setup` first), Kiro CLI (`kiro-cli`), Qoder CLI (`qodercli`), Qoder CN CLI (`qoderclicn`), Trae CLI (`traecli`), Grok Build CLI (`grok`), Qwen Code (`qwen`), and QwenPaw (`qwenpaw`; model picked in QwenPaw's own configuration) (raw/github_doc-self-hosting-md.md). ### Manual alternatives Manual Docker Compose: ```bash git clone https://github.com/multica-ai/multica.git cd multica cp .env.example .env # Edit .env — at minimum change JWT_SECRET: JWT_SECRET=$(openssl rand -hex 32) docker compose -f docker-compose.selfhost.yml pull docker compose -f docker-compose.selfhost.yml up -d ``` Manual CLI configuration: ```bash multica config set server_url http://localhost:8080 multica config set app_url http://localhost:3000 multica login multica daemon start ``` Manual build without Docker Compose (prerequisites: Go 1.26+, Node.js 20+, pnpm 10.28+, PostgreSQL 17 with pgvector): ```bash make build DATABASE_URL="your-database-url" ./server/bin/migrate up DATABASE_URL="your-database-url" PORT=8080 JWT_SECRET="your-secret" ./server/bin/server ``` ```bash pnpm install pnpm build cd apps/web REMOTE_API_URL=http://localhost:8080 pnpm start ``` (raw/github_doc-self-hosting-advanced-md.md) ### AI-agent-executable variant `SELF_HOSTING_AI.md` is a separate, terser guide "designed for AI agents to execute" — the same install path condensed into copy-pasteable steps with an explicit wait condition: ```bash curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash -s -- --with-server multica setup self-host ``` It instructs waiting for the server output `✓ Multica server is running and CLI is ready!` before running `multica setup self-host`, lists the same manual fallback (`git clone` + `make selfhost` + `brew install multica-ai/tap/multica` + `multica setup self-host`), and gives a compact troubleshooting map: check `docker compose -f docker-compose.selfhost.yml logs backend` / `logs frontend` for service issues, `multica daemon logs` for daemon issues, and `curl http://localhost:8080/health` (liveness) vs. `curl http://localhost:8080/readyz` (dependency-aware readiness) for health checks. Custom ports are changed by editing `PORT` / `FRONTEND_PORT` in `.env` (the containers still listen on 8080/3000 internally, so no rebuild is needed), then `make selfhost`, then `multica setup self-host --port <PORT> --frontend-port <FRONTEND_PORT>` (raw/github_doc-self-hosting-ai-md.md). ### Kubernetes deployment (alternative to Compose) The released OCI Helm chart lives at `oci://ghcr.io/multica-ai/charts/multica` (source at `deploy/helm/multica/`), authored against k3s + Traefik + `local-path` and adaptable to other clusters with an Ingress controller and a default `ReadWriteOnce` StorageClass. It creates `multica-postgres` (`pgvector/pgvector:pg17`, 10Gi PVC), `multica-backend`, `multica-frontend`, two Ingress resources, and a `multica-config` ConfigMap. The `multica-secrets` Secret is **not** managed by the chart — create it once so real values never touch git: ```bash kubectl create namespace multica kubectl -n multica create secret generic multica-secrets \ --from-literal=JWT_SECRET="$(openssl rand -hex 32)" \ --from-literal=POSTGRES_PASSWORD="$(openssl rand -hex 16)" \ --from-literal=RESEND_API_KEY="" \ --from-literal=GOOGLE_CLIENT_SECRET="" \ --from-literal=CLOUDFRONT_PRIVATE_KEY="" \ --from-literal=MULTICA_DEV_VERIFICATION_CODE="" helm install multica oci://ghcr.io/multica-ai/charts/multica \ --version <chart-version> \ -n multica ``` Released chart versions strip the leading `v` from the Git tag (release `v0.3.5` → chart `0.3.5`, defaulting image tags to `v0.3.5`). Check readiness: ```bash curl -H "Host: api.multica.dev.lan" http://<ingress-ip>/healthz # {"status":"ok","checks":{"db":"ok","migrations":"ok"}} ``` Then connect the daemon exactly as in Compose, pointed at the Ingress hostnames: ```bash multica setup self-host \ --server-url http://api.multica.dev.lan \ --app-url http://multica.dev.lan ``` To pull new images on the mutable `latest` tag: `kubectl -n multica rollout restart deploy/multica-backend deploy/multica-frontend`. To move to a specific release, bump the chart version and `helm upgrade`; `helm -n multica rollback multica` reverts. Tearing down: `helm -n multica uninstall multica` keeps PVCs and the Secret; `kubectl delete namespace multica` wipes everything (raw/github_doc-self-hosting-md.md). ### Upgrading Two equivalent upgrade paths for an existing Compose install — both end up calling the same `docker compose pull` + `up -d`: ```bash cd multica && git pull && make selfhost ``` ```bash cd multica && git pull && docker compose -f docker-compose.selfhost.yml pull && docker compose -f docker-compose.selfhost.yml up -d ``` `git pull` only updates `docker-compose.selfhost.yml` itself (new env vars, new services, healthchecks) — it is **not** how a new Multica version is obtained. The actual version comes from `docker compose pull` resolving `${MULTICA_IMAGE_TAG:-latest}` against GHCR. If `MULTICA_IMAGE_TAG` is pinned to an exact release in `.env`, neither command upgrades anything — check first: ```bash grep MULTICA_IMAGE_TAG .env # MULTICA_IMAGE_TAG=v0.4.5 ← pinned: edit to `latest` (or the target release) first ``` Back up Postgres before upgrading anything you care about, since migrations are forward-only: ```bash docker compose -f docker-compose.selfhost.yml exec -T postgres \ pg_dump -U multica multica > multica-backup.sql && gzip multica-backup.sql ``` Do not pipe `pg_dump` straight into `gzip` — a pipeline reports only the last command's exit status, so a failed dump can silently produce a tiny, empty `.gz` that still exits `0`. Redirecting to a file first, then `&&`-chaining `gzip`, ensures a failed dump is caught (raw/github_doc-apps-docs-content-docs-self-host-quickstart-mdx.md). Verify with `/readyz`, not `/health`: `/health` is a liveness probe that returns ok as long as the process is up, even mid-migration-failure; `/readyz` (`server/cmd/server/router.go:680`; `/healthz` is an alias) checks the database and applied migrations, so it is what actually catches a bad upgrade. Migrations run automatically inside the backend container on startup and are idempotent — there is no separate upgrade command; a rare automatic-backfill failure surfaces as `refusing to drop legacy daily rollups`, covered under [[concepts/troubleshooting]]. On Kubernetes, `helm upgrade` with a bumped image tag is the reliable upgrade path; `kubectl rollout restart` alone is **not** an upgrade when `pullPolicy: IfNotPresent` is in effect (the chart default) — a node with the tag already cached silently reuses the old image (raw/github_doc-apps-docs-content-docs-self-host-quickstart-mdx.md). `docker compose down` keeps the `pgdata` and `backend_uploads` volumes; adding `-v` deletes them, including the database — do not run `down -v` unless wiping the instance is intended. ### Switching to Multica Cloud / stopping services ```bash # Switch this machine's CLI to Cloud (local Docker services are unaffected) multica setup # Stop everything installed via the install script curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash -s -- --stop # Or, from a manual clone make selfhost-stop # stops Docker Compose services multica daemon stop # stops the local daemon ``` (raw/github_doc-self-hosting-md.md) ### Reverse proxy patterns (production) Same-origin (recommended) keeps `NEXT_PUBLIC_API_URL`/`NEXT_PUBLIC_WS_URL` empty and `COOKIE_DOMAIN` empty — the browser uses relative `/api` and `/ws` paths on one hostname, so no cross-host cookie problem can arise: ```bash # Backend FRONTEND_ORIGIN=https://app.example.com CORS_ALLOWED_ORIGINS=https://app.example.com COOKIE_DOMAIN= # Frontend NEXT_PUBLIC_API_URL= NEXT_PUBLIC_WS_URL= REMOTE_API_URL=http://backend:8080 ``` Split-domain (frontend and backend on different hostnames) requires `COOKIE_DOMAIN` set to the narrowest parent domain covering both hosts — omitting it breaks every write request with `403 {"error":"CSRF validation failed"}`, because the browser cannot read a cookie issued by a sibling host. `NEXT_PUBLIC_API_URL`/`REMOTE_API_URL` must be the backend's bare origin (scheme + host, no `/api` path) — a trailing path doubles into `/api/api/...` and breaks attachments/avatars/images with 404s (fixed defensively for a trailing `/api` specifically, but not other paths). Full Caddy and Nginx examples, including the required `/ws` WebSocket block with `flush_interval -1`, are in `SELF_HOSTING_ADVANCED.md` (raw/github_doc-self-hosting-advanced-md.md). See [[concepts/configuration]] for the complete variable reference and [[concepts/troubleshooting]] for the specific failure symptoms these misconfigurations produce. ## Key Parameters - Required ports free on the Docker host: `3000` (frontend), `8080` (backend/API). - `docker-compose.selfhost.yml` binds both ports to `127.0.0.1` only by default — never rebind to `0.0.0.0` for public exposure. - `MULTICA_IMAGE_TAG` — pin to an exact release (e.g. `v0.4.5`) to freeze upgrades; `.env.example` ships `latest`. - `JWT_SECRET`, PostgreSQL password, `MULTICA_VCS_SECRET_KEY` — auto-generated by `make selfhost` on first run only; never regenerated on re-run. - `/health` (liveness) vs. `/readyz` / `/healthz` (dependency-aware readiness, checks db + migrations) — always verify upgrades with `/readyz`. - Prerequisites for manual builds: Go 1.26+, Node.js 20+, pnpm 10.28+, PostgreSQL 17 with pgvector. - Compose volumes `pgdata` and `backend_uploads` survive `down`; only `down -v` deletes them. ## When To Use Choose Docker Compose for a single-machine or small-team deployment; choose the Kubernetes Helm chart when you already operate a cluster with an Ingress controller and default StorageClass. Use the one-command `--with-server` installer or `SELF_HOSTING_AI.md`'s condensed steps when an AI agent itself is performing the install (its instructions are written for exactly that). Use the manual (non-Docker) build path only when you need to run backend/frontend outside containers, e.g. for local development against source. ## Risks & Pitfalls - Pinning `MULTICA_IMAGE_TAG` silently freezes both `git pull`-based upgrade paths — no error, no warning, just the same version re-pulled. - `docker compose restart` does not re-read `.env`; only `up -d` recreates containers with new environment values. - `docker compose down -v` deletes the Postgres data volume — never run it on an instance you intend to keep. - Piping `pg_dump` directly into `gzip` masks a failed backup with a successful-looking empty archive; redirect to a file first. - On Kubernetes, `kubectl rollout restart` is a no-op upgrade when `pullPolicy: IfNotPresent` and the tag is unchanged — bump the tag and `helm upgrade` instead. - Split-domain deployments that omit `COOKIE_DOMAIN`, or that put a path on `NEXT_PUBLIC_API_URL`/`REMOTE_API_URL`, are two of the most common self-host misconfigurations — see [[concepts/troubleshooting]] and [[concepts/configuration]] for their exact symptoms. - Running the daemon under a personal user account defeats the entire security model described in [[concepts/security-model]] — use a dedicated user, container, or VM instead. ## Related Concepts - [[concepts/security-model]] — why the daemon's OS user, not Multica, is the real isolation boundary. - [[concepts/configuration]] — the complete environment-variable reference for everything configured here. - [[concepts/auth-and-tokens]] — sign-in and PAT behavior once the service is running. - [[concepts/troubleshooting]] — symptom-based diagnosis when self-hosting steps don't work as expected. ## Sources - raw/github_doc-apps-docs-content-docs-self-host-quickstart-mdx.md - raw/github_doc-self-hosting-md.md - raw/github_doc-self-hosting-advanced-md.md - raw/github_doc-self-hosting-ai-md.md <!-- ===== multica/wiki/concepts/skills.md ===== --> --- title: "Skills" type: concept tags: [agents, foundational, user, well-established] created: 2026-08-10 updated: 2026-08-10 sources: ["raw/github_doc-apps-docs-content-docs-skills-mdx.md"] confidence: high multica_version: "v0.4.22" --- ## Definition A skill is a reusable set of working methods in a workspace, packaged as a main `SKILL.md` file optionally accompanied by scripts, templates, and reference material. Adding a skill to an agent means the agent uses its guidance when executing related tasks, so a method no longer has to be copied into each agent's instructions, and updates are maintained in one place (raw/github_doc-apps-docs-content-docs-skills-mdx.md). ## How It Works **Skills vs. agent instructions:** | | Agent instructions | Skill | |---|---|---| | Best for | This agent's long-lived responsibilities, boundaries, and delivery requirements | Reusable steps, material, and tools for one kind of work | | Scope | Belongs to one agent, provided on every run | Can be added to multiple agents, enabled or disabled individually | | Example | "Only review frontend code, never modify it directly" | An accessibility checklist and report template | **Creating or importing a skill**: on the workspace **Skills** page, choose "New skill" with three options — **Create manually** (start from a blank `SKILL.md`), **Import from URL** (a published skill from GitHub, ClawHub, or Skills.sh), or **Copy from a runtime** (scan skills on a connected computer and copy selected ones into the workspace — this takes a snapshot at that moment; later local changes do not auto-update the workspace version). With the CLI, import from a `.skill` or `.zip` file: ```bash multica skill import --file ./review-helper.skill ``` If a skill with the same name already exists, import can stop, overwrite, save under a new name, or skip. Overwriting via import is limited to the skill's own creator — a workspace `admin` who can edit the skill in the app still cannot overwrite it via import. **Skill contents**: every skill has a main `SKILL.md` that should spell out when the skill applies, what to check before starting, the steps to execute, what form the result should take, and when to stop and check with a member. Supporting files can be added, e.g.: ```text SKILL.md references/api-conventions.md templates/review-report.md scripts/check.sh ``` `SKILL.md` is a reserved path — a supporting file cannot use that name. Supporting files are delivered to the agent together with the main file. **Attaching to an agent**: after creating or importing, a skill still needs to be added to specific agents, either from the skill page or from the agent's **Skills** tab. One agent can use multiple skills; one skill can serve multiple agents. When a skill isn't needed for now, disable the binding instead of deleting the skill. Edits take effect from subsequent runs and don't change tasks already running. Only members who can modify the agent can add, remove, or disable its skills. **Workspace skills vs. repository skills**: workspace skills are stored in Multica — a fit for skills the team maintains together and adds to different agents. Some AI coding tools also read project-level skills directly from the code repository, such as `.claude/skills/` or `.agents/skills/` — those stay managed by the repository, and Multica does not automatically register them as workspace skills; support depends on the tool in use. Runtime-local skills already installed on a connected computer (Claude Code and Codex) show up in the agent's **Skills** tab and can be disabled per agent, again requiring permission to modify the agent. **Edit permissions**: any workspace member can create or import a skill; the creator and workspace `owner`s/`admin`s can modify or delete it; other members can view and use it but cannot overwrite its content. Deletion is permanent and removes the skill from all agents at the same time. Multica follows the Anthropic Agent Skills open standard, so any skill matching the spec can be imported directly; once attached to an agent, it syncs to the runtime at execution time (raw/github_doc-apps-docs-content-docs-tutorial-mdx.md is a corroborating source for this open-standard detail, described in the tutorial's skills section). ## Key Parameters - Main file: `SKILL.md` (reserved name, cannot be used by a supporting file). - Import sources: manual creation, URL (GitHub, ClawHub, Skills.sh), or copy-from-runtime snapshot; CLI also supports `.skill`/`.zip` files. - Binding is many-to-many: one agent can carry multiple skills, and one skill can serve multiple agents. - Import name-collision options: stop, overwrite, save as new name, or skip. ## When To Use Use a skill when a working method needs to be shared across multiple agents, or reused from elsewhere, rather than copied by hand into each agent's instructions. Use plain agent instructions instead for that one agent's own long-lived responsibilities and boundaries — see the comparison table above. ## Risks & Pitfalls - Skills imported from external sources may contain scripts, commands, or unsafe instructions; Multica does not review, sign, or sandbox them, and imported content is handed to agents as-is — the source needs to be trusted (raw/github_doc-apps-docs-content-docs-skills-mdx.md). The tutorial reinforces this: read a third-party skill's files before importing (raw/github_doc-apps-docs-content-docs-tutorial-mdx.md). - Copying from a runtime is a one-time snapshot — later edits to the local files on that computer will not propagate to the workspace copy automatically; re-import or edit in Multica directly. - Deleting a skill is permanent and removes it from every attached agent simultaneously — there is no soft-delete; disable the binding instead if the intent is temporary. - Repository-level skill directories (`.claude/skills/`, `.agents/skills/`) are not automatically picked up as workspace skills — relying on that path silently leaves the workspace's Skills page out of sync with the repo. ## Related Concepts - [[concepts/core-concepts]] — where skills sit relative to agents, tasks, and squads. - [[concepts/squads]] — squads and skills both let a working method scale beyond a single agent, via different mechanisms (routing vs. reuse). - [[concepts/getting-started]] — the tutorial's worked example of importing a TDD skill and a reporting-style skill. - [[concepts/multica-overview]] — skills as part of "turn a solved problem into a playbook every agent reuses." ## Sources - raw/github_doc-apps-docs-content-docs-skills-mdx.md - raw/github_doc-apps-docs-content-docs-tutorial-mdx.md (corroborating detail on the Anthropic Agent Skills standard and import-safety guidance) <!-- ===== multica/wiki/concepts/squads.md ===== --> --- title: "Squads" type: concept tags: [agents, workflow, advanced, user, well-established] created: 2026-08-10 updated: 2026-08-10 sources: ["raw/github_doc-apps-docs-content-docs-squads-mdx.md"] confidence: high multica_version: "v0.4.22" --- ## Definition A squad is one leader agent plus any number of members (agents or human members), used when a piece of work needs several capabilities and the specific owner can't be determined at issue-creation time. Assigning an issue to a squad does not run every agent at once — Multica wakes the leader first, and it reads the context and decides who takes the next step (raw/github_doc-apps-docs-content-docs-squads-mdx.md). ## How It Works **Composition:** | Setting | What it does | |---|---| | Leader | Must be an agent; receives work assigned to the squad and decides how to handle it | | Members | Can be agents or human members; the same member can join multiple squads | | Role descriptions | Tell the leader what work each member is suited for — context only, granting no permissions and never auto-triggering members | | Squad instructions | Routing rules, collaboration norms, squad-wide background — provided to the leader only | Creating a squad requires a name and a leader; the leader automatically becomes a member. **Execution flow after assignment**, when a non-Backlog issue is assigned to a squad: 1. **Leader claims the task** — Multica enqueues a task for the leader agent only (not every member), and the runtime picks it up like any agent assignment. 2. **Leader is briefed** — three sections are appended to the leader's system prompt on claim: the Squad Operating Protocol, the Squad Roster, and the Squad Instructions. 3. **Leader moves the parent to `in_progress`** on the first turn — the same agent-managed status contract as a direct assignment. Dispatching members is not completion; the parent stays `in_progress` while the squad works. 4. **Leader posts one delegation comment**, `@`-mentioning the chosen member(s) using the exact mention markdown from the roster — that mention triggers a new task for each mentioned agent. 5. **Leader records its evaluation** via `multica squad activity <issue-id> action --reason "..."`, writing an entry to the issue's activity timeline so humans can see it actually evaluated the trigger. 6. **Leader stops** — it does not implement the work itself. It is re-triggered when a delegated member posts back, or when a sub-issue/stage barrier closes, and then either delegates the next step, escalates, moves the parent to `in_review` once the overall goal is met, or stays silent. `done` is left to a human reviewer or existing integrations (e.g. a PR with close intent that merges). If the issue is in **Backlog**, the leader is not triggered — the same rule as for direct agent assignment. **What the leader sees on every turn** — three system-appended blocks: the **Squad Operating Protocol** (hard-coded, system-managed, not editable: read the issue, move to `in_progress` on first turn, delegate by `@`-mention, be terse, record an evaluation every turn, stop after dispatching, only move to `in_review` once the goal is met — scoped to issues actually assigned to this squad; a leader woken by an `@squad` mention on someone else's issue must not touch that issue's status); the **Squad Roster** (leader's self-row plus one row per non-archived member, each with the exact mention markdown `[@Name](mention://agent/<uuid>)` or `[@Name](mention://member/<uuid>)` — a plain `@name` will not trigger anyone); and the **Squad Instructions** (custom guidance set on the squad detail page or via `multica squad update --instructions`). **Leader re-trigger rules** after the first dispatch: | Event | Leader triggered? | |---|---| | A non-member posts a comment | Yes | | A squad member posts a progress update with no `@mention` | Yes — leader re-evaluates whether a next step is needed | | Anyone posts a comment that explicitly `@`-mentions another agent/member/squad/`@all` | No — the explicit `@` is the routing signal | | The leader's own comment (self-trigger) | No — guarded against loops | | A comment containing only an issue cross-reference | Yes — issue references aren't routing | Dedup applies on top: if the leader already has a `queued` or `dispatched` task on the issue, a new trigger won't enqueue a duplicate. Agent-authored comments are the one exception to the "explicit @ means no leader wake-up" rule — when an agent posts a result that `@`s another agent, the leader still wakes to coordinate the thread. **Assigning vs. @-mentioning a squad:** | Action | Changes the assignee | Result | |---|---|---| | Assign an issue to a squad | Yes | The squad becomes the assignee and the leader is triggered | | @-mention a squad in a comment | No | The leader handles that comment only; the current assignee is unchanged | **Archiving**: once archived, a squad disappears from lists, assignee pickers, and the @-menu, and cannot be restored. Issues and automations currently assigned to the squad transfer to the former leader agent to keep ownership intact; historical comments/activity remain. This is not undoable. **CLI:** ```bash multica squad create --name "Product Delivery" --leader delivery-lead multica squad member add <squad-id> \ --member-id <agent-or-member-id> \ --type agent \ --role "Owns frontend implementation" ``` ## Key Parameters - Leader must be an agent (never a plain member). - Role descriptions and squad instructions are context, not access control — they grant no permissions. - Mention markdown format: `[@Name](mention://agent/<uuid>)` or `[@Name](mention://member/<uuid>)`. - Squad names need not be unique within a workspace. ## When To Use Use a squad when the work needs several capabilities and the specific owner can't be determined when the issue is created — e.g. a product-delivery squad with frontend, backend, and testing agents, routed per-issue by the leader. When the scope is already clear, assign directly to the matching agent instead — see [[concepts/assigning-issues]]. ## Risks & Pitfalls - Adding an agent to a squad does not bypass its own Access — regular members creating or managing squads can only pick agents they are allowed to run, and whether a member can assign/@-mention a squad depends on whether they can run the squad's leader (raw/github_doc-apps-docs-content-docs-squads-mdx.md). See [[concepts/assigning-issues]]. - If the leader is archived, or the member isn't allowed to run it, the squad can't be assigned or @-mentioned at all. - Archiving a squad cannot be undone; if the same routing is needed again later, a new squad must be created. - Typing a plain `@name` instead of the roster's exact mention markdown will not trigger anyone — this is a common source of "nothing happened" confusion. - The current leader cannot be removed directly from a squad — a new leader must be designated first, and it then joins the squad automatically. ## Related Concepts - [[concepts/assigning-issues]] — assignment mechanics that squads build on, and the member/agent/squad comparison. - [[concepts/board-and-work-items]] — the issue status contract the leader follows (`in_progress` → `in_review`). - [[concepts/getting-started]] — the tutorial's worked example of forming a squad (Lead, Engineer, Reviewer). - [[concepts/core-concepts]] — where squads sit relative to agents, tasks, and issues in the domain model. ## Sources - raw/github_doc-apps-docs-content-docs-squads-mdx.md <!-- ===== multica/wiki/concepts/triggering-and-mentioning-agents.md ===== --> --- title: "Triggering and Mentioning Agents" type: concept tags: [agents, workflow, communication, foundational, user] multica_version: "v0.4.22" created: 2026-08-10 updated: 2026-08-10 sources: ["raw/github_doc-apps-docs-content-docs-triggering-agents-mdx.md", "raw/github_doc-apps-docs-content-docs-mentioning-agents-mdx.md"] confidence: high --- ## Definition In Multica, [[concepts/agents]] never start work on their own — every run is triggered by an explicit action. This concept covers the four ways to trigger an agent (assignment, @-mention, direct chat, autopilot) and, in more depth, the mechanics of @-mentioning an agent in an issue comment: how the trigger preview works, how plain replies get routed automatically, and how consecutive comments coalesce into a single run. ## How It Works **The four trigger methods:** | Method | Best for | How | | --- | --- | --- | | Assign an issue | The agent owns this work end to end | Assigning the issue to an agent; it starts immediately once the issue is in `todo` or a later status | | @mention in a comment | Ask an agent to handle one specific request without changing the assignee | @mention it in a comment, or reply to the agent's comment to continue the conversation | | Direct chat | A question or quick attempt that doesn't need an issue | Start a chat with the agent; each message triggers one run | | Autopilot | Recurring work on a schedule or external event | Create an autopilot, triggered by a schedule, a webhook, or manually (see [[concepts/autopilots]]) | Shared rules across all four: you can only trigger agents you have permission to run, per the agent's Access setting (see [[concepts/agents]]#permissions-and-access) — your workspace role doesn't matter. Before triggering from an issue, a **trigger preview** under the input shows exactly who this content will wake; prefixing with `/note` leaves a message without triggering anyone. Issues in `backlog` never trigger runs — moving an issue to `todo` is what starts its assigned agent. Every trigger creates a task. Progress streams back to wherever it was triggered — the issue's timeline or the chat window — and the execution log shows the full run, letting you stop or retry it. A run that's slow to start usually means the runtime is offline (see [[concepts/providers-and-runtimes]]). **Assigning vs. @-mentioning**, compared directly: | | Assign to an agent | @-mention in a comment | |---|---|---| | Best for | Making the agent own the whole issue | Having the agent handle the current comment | | Changes the assignee | Yes | No | | Changes the status | No | No | | Targets per action | One agent or squad | Multiple agents or squads | | Focus of the run | The whole issue | The triggering comment, plus comments merged in the same batch | **Trigger preview for mentions.** After picking an agent or squad in the comment editor, the preview under the input shows: which agents will start once you send; whether each target comes from a direct @-mention, the issue assignee, or a squad leader; and whether a target is unavailable or you lack permission to run it. Unticking an agent skips just that one trigger — it doesn't remove its name from the comment text or change its Access. Once posted, an online runtime usually claims the task right away; if offline, it queues. **Automatic routing of plain replies.** A comment containing no `@` at all is routed by discussion context, in order: 1. Replying to an agent's comment hands the new comment to that agent. 2. Replying inside a discussion an agent already participates in keeps that discussion's agent. 3. Otherwise it goes to the issue's agent assignee; if the assignee is a squad, the squad leader handles it. As soon as a comment explicitly @-mentions other targets (including human members), this assignee-fallback chain no longer applies. **Delayed fallback for the assignee.** When a reply ends up triggering an agent *other than* the assignee, Multica schedules a delayed fallback run for the assignee about 5 minutes later; if the actually-mentioned agent replies within that window, the fallback is cancelled automatically, otherwise the assignee runs too. **Coalescing consecutive comments.** If the same agent already has a waiting task on the issue, new consecutive comments merge into that pending task; if the agent is already running, later comments wait and merge into a single follow-up run once it finishes — so you can keep adding context without waiting for a reply each time. When one comment @-mentions several different agents, each gets its own task; multiple mentions resolving to the same agent still produce only one task. **Comments that don't trigger agents.** Two mechanisms: starting a comment with `/note` posts it as a note between human members with no agent triggered; using `@all` notifies every workspace member and switches off the comment's automatic trigger for the assignee. `@all` does *not* include agents — agents have no inbox, so the only ways to put one to work are an explicit @-mention, a reply inside its discussion, or an issue assignment. If the trigger preview still lists an agent after using `/note` or `@all`, untick it before sending. **Access restrictions.** An @-mention cannot bypass an agent's Access setting. When you lack permission to run the target, the target is archived, or it has no available runtime, the trigger preview explains that it won't start — but the comment itself still posts normally. **Agents mentioning each other.** Agents can @-mention other agents in their replies. If agent A @-mentions B and B @-mentions A back, the system merges duplicate runs happening at the same moment — but it does not decide when the back-and-forth should stop; that stop condition has to be written into the agents' instructions (see [[concepts/creating-agents]]). ## Key Parameters - **Issue status gate** — `backlog` never triggers; `todo` or later does. - **Fallback delay** — ~5 minutes before the assignee's fallback run fires after a non-assignee reply. - **Trigger-suppressing syntax** — `/note` (no trigger at all) and `@all` (notifies humans, suppresses the assignee's automatic trigger, but still excludes agents). - **Coalescing window** — indefinite while a task is "waiting" or "running"; consecutive comments merge until the run actually starts/finishes. ## When To Use - Assign an issue when an agent should own it end to end and move it through the board. - @-mention when you want a specific agent's input on one comment without disturbing the assignee. - Reply without an `@` when you want the conversation's existing routing (agent's own comment, or the discussion's established agent) to just keep working. - Explicitly @-mention a different target when you deliberately want to route around the default assignee/discussion agent. - Use `/note` for a comment that's purely for human coordination. - Rely on autopilots, not manual mentions, for anything that should recur on a schedule or webhook — see [[concepts/autopilots]]. ## Risks & Pitfalls - Assuming `@all` reaches agents — it explicitly does not; agents have no inbox. - Assuming unticking an agent in the trigger preview changes its Access — it only skips that one trigger. - Explicit @-mentions silently disable the assignee-fallback chain, which can leave the nominal owner out of a conversation unless the ~5-minute delayed fallback catches it. - Agent-to-agent @-mention chains have no automatic stop condition — without an explicit rule in the agents' instructions, A-and-B back-and-forth mentioning can continue indefinitely (duplicate simultaneous runs are merged, but that's not the same as ending the loop). - A comment that mentions an unavailable, unpermitted, or archived agent still posts — don't assume the presence of a comment means the trigger actually fired; check the trigger preview or execution log. - Moving an issue only to `backlog` (not `todo`+) will never start its assignee, even if one is set. ## Related Concepts - [[concepts/agents]] — the Access rules and participation model that trigger mechanics build on. - [[concepts/creating-agents]] — where agent instructions need to define stop conditions for agent-to-agent mentions. - [[concepts/providers-and-runtimes]] — why a triggered run might sit queued instead of starting immediately. - [[concepts/assigning-issues]] (planned) — the assignment half of the trigger-method table in more depth. - [[concepts/board-and-work-items]] (planned) — the `backlog`/`todo` status gate in the context of the whole board. - [[concepts/communication]] (planned) — comments, `/note`, `@all`, and notification behavior more broadly. - [[concepts/squads]] (planned) — how squad leaders receive assignee-fallback and mention routing. - [[concepts/autopilots]] (planned) — the fourth trigger method, in depth. - [[concepts/troubleshooting]] (planned) — diagnosing a trigger that doesn't seem to start a run. ## Sources - raw/github_doc-apps-docs-content-docs-triggering-agents-mdx.md - raw/github_doc-apps-docs-content-docs-mentioning-agents-mdx.md <!-- ===== multica/wiki/concepts/troubleshooting.md ===== --> --- title: "Troubleshooting" type: concept tags: [self-hosting, operator, advanced, emerging] created: 2026-08-10 updated: 2026-08-10 sources: ["raw/github_doc-apps-docs-content-docs-troubleshooting-mdx.md", "raw/github_issue-ask-about-local-usage-issues.md", "raw/github_issue-bug-agent-invocation-fails-frequently.md", "raw/github_issue-bug-agent-triggered-comments-can-be-stored-displayed-as-memb.md", "raw/github_issue-bug-attachment-download-not-working-on-desktop.md", "raw/github_issue-bug-codex-0-143-0-144-app-server-starts-but-multica-returns-.md", "raw/github_issue-bug-comment.md", "raw/github_issue-bug-creating-an-issue-through-an-agent-fails.md", "raw/github_issue-bug-desktop-app-fails-to-launch-after-updating-to-0-3-7.md", "raw/github_issue-bug-docker-compose-0-1-35.md", "raw/github_issue-bug-images-cannot-be-recognized-by-the-agent.md", "raw/github_issue-bug-issue-activity.md", "raw/github_issue-bug-issue-comment-input-briefly-loses-focus-while-agents-loa.md", "raw/github_issue-bug-issue.md", "raw/github_issue-bug-pi-agents-stuck-in-working-mode.md", "raw/github_issue-bug-self-host-on-orbstack-tasks-wedge-in-queued-daemon-skips.md", "raw/github_issue-bug-self-host-session-is-not-stable.md", "raw/github_issue-bug-the-agent-doesn-t-know-which-warehouse-to-choose.md", "raw/github_issue-bug-the-request-has-been-blocked.md", "raw/github_issue-bug-timeline-filter-is-not-a-function.md", "raw/github_issue-bug-turn-completed-tasks-idle-reaped-as-failed-empty-result-.md", "raw/github_issue-chat-thread-does-not-auto-refresh-after-agent-responds-stuck.md", "raw/github_issue-cli-json-payloads-exhaust-agent-context-recent-n-is-ignored-.md", "raw/github_issue-discussion-should-agents-bind-to-a-local-directory-or-stay-w.md", "raw/github_issue-feature-claude-code.md", "raw/github_issue-feature-private-runtime.md", "raw/github_issue-feature-register-multica-agent-as-a-dingtalk-bot.md", "raw/github_issue-feature-support-soft-delete-or-archive-issue.md", "raw/github_issue-feature.md", "raw/github_issue-how-to-add-a-local-project-mapping.md", "raw/github_issue-how-to-debug-codex-returned-empty-output.md", "raw/github_issue-if-i-have-multiple-repos-how-does-the-agent-know-which-repo-.md", "raw/github_issue-openclaw.md", "raw/github_issue-rewriting-claude-md-on-every-run-discards-the-whole-prompt-c.md", "raw/github_issue-self-host-upgrade-note-v0-3-4-v0-3-5-requires-task-usage-bac.md", "raw/github_issue-some-feedback.md", "raw/github_issue-untitled-2.md", "raw/github_issue-untitled.md", "raw/github_issue-why-can-t-i-run-more-than-one-task-simultaneously-in-a-singl.md"] confidence: medium multica_version: "v0.4.22" --- ## Definition Troubleshooting Multica means first identifying *which layer* a problem lives in — the Multica service, the daemon, the runtime, or the AI coding tool itself — and then following a symptom-specific playbook (raw/github_doc-apps-docs-content-docs-troubleshooting-mdx.md). This page combines the official troubleshooting doc's diagnostic playbooks with recurring, confirmed problems pulled from ~60 mirrored GitHub issues, each annotated with its status as of the mirrored snapshot (fetched 2026-08-10). Status labels below are `fixed` (a specific PR/version is cited), `workaround` (no real fix, but a working mitigation exists), or `open` (unresolved as of the mirror) — never invented. ## How It Works ### First diagnostic pass ```bash multica version multica auth status multica daemon status --output json multica daemon logs --lines 100 ``` Self-hosted instances can also check the service directly: `curl -i https://api.example.com/health` (liveness only) and `curl -i https://api.example.com/readyz` (also checks database and migrations). Include the error, relevant logs, CLI version, and OS when reporting a problem, and strip tokens/emails/sensitive detail first (raw/github_doc-apps-docs-content-docs-troubleshooting-mdx.md). ### Documented symptom playbooks - **Daemon fails to connect** — check sign-in/token expiry, whether the daemon points at the right service, network/DNS/TLS/firewall reachability *from the executing computer* (not the server), workspace membership, and whether any supported AI coding tool is installed. Fix path: `multica login` then `multica daemon restart`; check the profile's `server_url` with `multica config show`. - **Issue does not start executing (`queued`)** — check in order: is the bound runtime online, did it detect the configured AI coding tool, does the agent have concurrency headroom, does the daemon have global execution capacity. An agent runs at most **6 tasks concurrently by default**; a daemon runs at most **20**. Tasks queue indefinitely while a runtime is offline and only fail after **2 hours** unclaimed. - **`waiting_local_directory` status** — another in-flight task holds the same local directory (see [[concepts/configuration]]). The mutex lives only in daemon memory (no lock file); `multica daemon restart` releases stale lock state. - **AI coding tool fails to start** — check sign-in, API key/quota/model permissions, whether the selected model/thinking level is supported, working-directory writability, and custom args/env validity. Run the same tool directly in a terminal first to isolate tool-side vs. Multica-side failure. - **Realtime updates stop working** — usually a WebSocket problem. Check `/ws` in DevTools Network; for self-hosted, check `FRONTEND_ORIGIN` matches the real browser address, `wss://` over HTTPS, reverse-proxy WebSocket forwarding, and session expiry. Containers only re-read `.env` on `up -d`, not `restart`. - **Verification codes / invitations not delivered** — check the backend startup log for `EmailService:` (states `SMTP relay`, `Resend API`, or `DEV mode`); DEV mode never sends real mail. See [[concepts/auth-and-tokens]]. - **Attachment uploads/downloads fail** — check reverse-proxy body-size limits, local upload directory writability/persistence, S3 bucket/region/endpoint/credential mismatch, and download-URL domain/protocol after a proxy hop. - **Usage shows zero** — the Usage page reads hourly rollups (`task_usage_hourly`), not raw `task_usage`. If raw data exists but rollups don't, and the scheduler shows failures, confirm migrations (especially 103) applied; `SELECT rollup_task_usage_hourly();` can be run by hand to isolate SQL vs. scheduling problems, but only fills one rollup. - **Migration 103 blocks an upgrade** — normally self-healing (`migrate up` auto-backfills before applying 103). If it still fails with `refusing to drop legacy daily rollups`, run `DATABASE_URL='postgres://...' go run ./cmd/backfill_task_usage_hourly` (flags: `--dry-run`, `--sleep-between-slices`) then restart the backend; the command is idempotent and safe to interrupt/rerun. See [[concepts/self-hosting]]. - **Port already in use** — find the holder (`lsof -nP -iTCP:8080 -sTCP:LISTEN` / `netstat -ano | findstr :8080`); if it's another Multica checkout, `make stop` there first. - **Log locations** — `multica daemon logs --lines 100` / `--follow`; `~/.multica/daemon.log` and `daemon.err.log` (or under `~/.multica/profiles/<name>/`); Docker backend via `docker compose -f docker-compose.selfhost.yml logs -f backend`; foreground startup via `multica daemon stop && multica daemon start --foreground`. (All of the above: raw/github_doc-apps-docs-content-docs-troubleshooting-mdx.md) ## Key Parameters - Default agent concurrency: 6 tasks; default daemon concurrency: 20 tasks (troubleshooting doc). - Unclaimed-task failure threshold: 2 hours in `queued` with no runtime claim. - `/health` = liveness only; `/readyz` / `/healthz` = dependency-aware (db + migrations) — always the one to trust after an upgrade. - The `waiting_local_directory` lock is in-memory only, per daemon — restarting the daemon clears it. - Migration 103's fail-closed guard (`refusing to drop legacy daily rollups`) requires `task_usage_hourly` seeded before it can apply; the `migrate up` auto-backfill (MUL-2957) handles this on a normal upgrade path. ## Known Recurring Issues (from GitHub Issue Reports) The following clusters are drawn from reading the ~60 `raw/github_issue-*.md` mirrors directly; status reflects only what each mirror shows as of its 2026-08-10 fetch, not the issue's current live state on GitHub. **Windows-specific runtime failures (the weakest platform in the mirrors).** A Windows-only stdin/pipe deadlock caused squad/multi-agent tasks to sit "waiting for events" for over an hour with zero execution records — root cause was the daemon writing a large prompt to Claude's stdin before starting the stdout reader, deadlocking on Windows' ~4KB pipe buffer (vs. 64KB on macOS/Linux); **fixed** by PR #3490 (raw/github_issue-bug-agent-invocation-fails-frequently.md). A Windows Codex sandbox setting (`sandbox_mode=workspace-write`, requiring `codex-windows-sandbox-setup.exe`) caused `multica issue create` calls from an agent to be silently rejected; **fixed** by PR #5672 switching Windows to `danger-full-access` in v0.4.7, though a later comment in the same mirror says "似乎问题仍然存在" (still seems to persist) — treat as fixed-then-reopened (raw/github_issue-bug-creating-an-issue-through-an-agent-fails.md). Chinese-language comment and issue content rendering as `?` mojibake on Windows remains **open** in both mirrors that report it, with a maintainer explicitly stating "还没修好上线" (not fixed yet) in one of them (raw/github_issue-bug-comment.md, raw/github_issue-bug-issue.md). A Windows-only IME (Chinese pinyin) focus-loss bug in the comment box is **unclear** — the maintainer could not reproduce it on macOS, and the reporter later suspected a Windows system-level keyboard-list bug rather than Multica itself (raw/github_issue-bug-issue-comment-input-briefly-loses-focus-while-agents-loa.md). **Codex runtime fragility.** Codex CLI 0.143/0.144 would start its app-server but return zero output while 0.125 worked; after a multi-round investigation (an initial "cold model-catalog refresh" theory turned out wrong), the confirmed root cause was that the task's `codex-home/sessions` was symlinked to the entire machine's `~/.codex/sessions` (~2,000 files / ~22GB), and Codex 0.144.x walks that aggregate history during `initialize`, timing out. **Fixed** by PR #5360 (per-task session isolation, shipped v0.4.2) plus PR #5319 (bounded app-server startup RPC timeout, shipped v0.4.0) (raw/github_issue-bug-codex-0-143-0-144-app-server-starts-but-multica-returns-.md). Agent-triggered comments sometimes get attributed to a human member instead of the agent; this appeared fixed around v0.2.24 but **regressed at v0.2.28**, and investigation had narrowed it specifically to the Codex runtime (Copilot CLI unaffected) with no final resolution recorded in the mirror — status **open**/recurring (raw/github_issue-bug-agent-triggered-comments-can-be-stored-displayed-as-memb.md). A separate report of Codex returning empty output ends without a confirmed resolution in the mirror — status **open** (raw/github_issue-how-to-debug-codex-returned-empty-output.md). **Agent task-completion detection ("stuck working" / idle-reaped).** This is the largest confirmed bug family across the mirrors — several independent runtime backends fail to detect that an agent actually finished, because completion is inferred from process exit rather than a protocol-level signal. Pi-backed agents stay "working" forever after finishing because Pi's event loop never exits when the daemon spawns it under systemd with `stdin=/dev/null`; the reporter's own fix is a Pi extension that force-calls `process.exit(0)` on `agent_end` when not a TTY — status **workaround**, not officially shipped in the mirror (raw/github_issue-bug-pi-agents-stuck-in-working-mode.md). OpenClaw had the same shape of bug: buffered `--json` output meant `CompleteTask` was never called until the user manually clicked stop; **fixed** by PR #836, but the same mirror's final comments report OpenClaw then failing to exit its own process afterward, relying on the daemon's 20-minute timeout to kill it — a maintainer question about whether that is expected OpenClaw behavior is left open at the end, so treat as fixed-then-partially-recurring (raw/github_issue-openclaw.md). Completed Claude/Codex agent turns get idle-reaped as `failed` with an empty result after 30 minutes because the Claude backend only finalizes on process exit rather than on the `result` marker itself (a foreground child process inheriting stdio can keep `claude` alive indefinitely); a related bug means failed delegated tasks never wake the parent squad leader. Both are confirmed by maintainers with a described fix direction, but no "shipped in vX" comment is present — status **open**/in-progress (raw/github_issue-bug-turn-completed-tasks-idle-reaped-as-failed-empty-result-.md). Self-hosted OrbStack deployments hit a related-but-distinct symptom: tasks wedged in `Queued` because the daemon could send a WebSocket `tasks.claim` RPC to an older backend lacking `rpc-v1` support and then skip its HTTP-claim fallback; **fixed** by PR #5422 (explicit RPC capability negotiation), confirmed working on v0.4.2 (raw/github_issue-bug-self-host-on-orbstack-tasks-wedge-in-queued-daemon-skips.md). **Self-host deployment/infrastructure gaps.** A docker-compose upgrade to v0.1.35 broke frontend↔backend communication because Caddy forced an HTTP→HTTPS redirect and the frontend build baked in a hardcoded port 8080; **fixed** by removing Caddy from `docker-compose.selfhost.yml` and clearing the `NEXT_PUBLIC_API_URL`/`NEXT_PUBLIC_WS_URL` defaults so the frontend uses relative paths (raw/github_issue-bug-docker-compose-0-1-35.md). A strict `frame-ancestors 'none'` CSP blocked attachment/file previews on self-host; a first fix covered only same-origin deployments, and a follow-up (PR #4539, shipped v0.3.30) allowed the configured frontend origin in the CSP for split-domain setups — **fixed** (raw/github_issue-bug-the-request-has-been-blocked.md). Chat stayed stuck on "queued" until manual refresh when accessed via a non-localhost URL, because the backend's `Upgrader.CheckOrigin` defaults to localhost-only and rejected the WebSocket upgrade with 403; **fixed** by setting `CORS_ALLOWED_ORIGINS`/`FRONTEND_ORIGIN`, confirmed working by the reporter (raw/github_issue-chat-thread-does-not-auto-refresh-after-agent-responds-stuck.md). Self-host session instability — clicking an issue triggers a cascade of 400s and reloading loses the session — remains **open**/unresolved in its mirror; diagnosis at the mirror's end pointed at `SameSite=Strict` cookie policy, a missing `NEXT_PUBLIC_API_URL` on the Docker frontend, or a possible JWT race, but no confirmed fix (raw/github_issue-bug-self-host-session-is-not-stable.md). The v0.3.4→v0.3.5 self-host upgrade required a manual `task_usage_hourly` backfill and `pg_cron` registration before the fix documented in [[concepts/self-hosting]] and [[concepts/troubleshooting]]'s migration-103 section existed — status **fixed/workaround** depending on the version upgraded from (raw/github_issue-self-host-upgrade-note-v0-3-4-v0-3-5-requires-task-usage-bac.md). **Attachment/file handling.** Desktop could preview but not download agent-generated attachments; two separate causes were found and fixed — a self-host misconfiguration (`LOCAL_UPLOAD_DIR`/`LOCAL_UPLOAD_BASE_URL` not forwarded in `docker-compose.selfhost.yml`) and a real bug where Electron's `webContents.downloadURL()` didn't carry Desktop's Bearer auth token, causing `401 missing authorization`, fixed via PR #5416 — **fixed** (raw/github_issue-bug-attachment-download-not-working-on-desktop.md). Claude Code (Opus) sometimes hallucinates a generic description of an uploaded image; the daemon log showed the image was correctly downloaded and base64-encoded, but the user's own verification attempt then hit a `404 attachment not found` when trying to re-download via CLI, and the thread ends there — status **open** (raw/github_issue-bug-images-cannot-be-recognized-by-the-agent.md). **Context bloat / prompt-cache cost (a connected engineering saga, heavily instrumented by reporters).** Rewriting `CLAUDE.md` on every run (to embed the triggering comment's UUID and other per-run fields) discarded the entire Claude prompt cache on every resumed run — measured at 76% of one workspace's weekly cache-write spend (~$384 of $507). The fix (byte-stable `CLAUDE.md`, volatile fields moved to the per-turn user message instead) had actually been written three times in independent PRs months earlier and sat unreviewed for 81 days before this issue prompted a review; **fixed** via PR #6021, shipped in v0.4.13, with a measured −98.0% cache-write per resumed run in the maintainers' own before/after test (raw/github_issue-rewriting-claude-md-on-every-run-discards-the-whole-prompt-c.md). A related report that CLI JSON payloads (`multica issue get`/`comment list`) exhaust agent context, and that `--recent N` appears ignored, turned out to be partly a misunderstanding (`--recent N` caps threads, not comments — the reporter retracted after re-testing) but did surface real fixes: PR #6093 rewrote the injected agent instructions toward `--roots-only --summary` plus targeted `--thread`/`--tail` (91.9%/92.6% payload reduction measured independently by two reporters), and PR #6119 shipped opt-in stable, much shorter attachment download URLs (803→62 chars) — status **partially fixed**, with a `--fields` projection request still tracked as **open** (raw/github_issue-cli-json-payloads-exhaust-agent-context-recent-n-is-ignored-.md). **Repo/working-directory selection friction (conceptual, not strictly a bug).** The single most-repeated point of user confusion across the mirrors is the worktree-per-task model versus "just point the agent at my existing folder" — visible across roughly a dozen separate issues and discussions (raw/github_issue-bug-the-agent-doesn-t-know-which-warehouse-to-choose.md, raw/github_issue-discussion-should-agents-bind-to-a-local-directory-or-stay-w.md, raw/github_issue-how-to-add-a-local-project-mapping.md, raw/github_issue-if-i-have-multiple-repos-how-does-the-agent-know-which-repo-.md, raw/github_issue-some-feedback.md, raw/github_issue-untitled.md, raw/github_issue-untitled-2.md, raw/github_issue-why-can-t-i-run-more-than-one-task-simultaneously-in-a-singl.md, raw/github_issue-ask-about-local-usage-issues.md). The concrete feature that shipped in response — the `local_directory` project resource (see [[concepts/configuration]]) — introduced its own confirmed follow-on friction: tasks on the same local directory serialize strictly one at a time (confirmed by design in raw/github_issue-why-can-t-i-run-more-than-one-task-simultaneously-in-a-singl.md), and `CLAUDE.md`/`AGENTS.md` gets overwritten rather than merged when a project is bound to an existing local checkout (noted, unresolved, in raw/github_issue-feature-claude-code.md). **Miscellaneous UI bugs.** A backend response-shape change to `/api/issues/:id/timeline` (array → paginated object) in v0.2.26 crashed the issue detail view on older desktop clients with `TypeError: timeline.filter is not a function`; **fixed** by updating Desktop to ≥v0.2.26 or hard-refreshing web, with a server-side backward-compatibility fix planned (raw/github_issue-bug-timeline-filter-is-not-a-function.md). Desktop app failing to launch after auto-updating to v0.3.7 (multiple Windows 11 confirmations) and stale "working" status in Issue Activity until manual refresh are both **unclear** in their mirrors — no fix or workaround is recorded, though the latter's reporter later noted the symptom no longer occurred on Desktop (raw/github_issue-bug-desktop-app-fails-to-launch-after-updating-to-0-3-7.md, raw/github_issue-bug-issue-activity.md). **Known gaps surfaced as feature requests, not bugs** (excluded from the status tally above but relevant context for an operator): per-user private runtime access control is only partially shipped — agent `visibility` and run-history restriction exist, but whether an admin can still invoke another user's private agent is undecided (raw/github_issue-feature-private-runtime.md); a fully custom/arbitrary local runtime is not supported — Multica currently requires declaring an underlying supported protocol such as codex or claude (raw/github_issue-feature.md); soft-delete/archive for issues was deliberately declined as a design stance (raw/github_issue-feature-support-soft-delete-or-archive-issue.md); DingTalk bot integration was requested here as community demand only — it later shipped as a community-maintained integration in v0.4.20 (see [[summaries/release-digest]]) (raw/github_issue-feature-register-multica-agent-as-a-dingtalk-bot.md). ## When To Use Start with the official playbooks above for connection, execution, realtime, email, attachment, and migration problems — they're maintained and version-agnostic. Cross-check the recurring-issues list above when the symptom matches a known pattern (Windows + Chinese text, Codex silently producing no output, an agent stuck "working" long past when it should have finished, a self-hosted split-domain deployment misbehaving) before assuming it's novel. Treat every "open" status as current-as-of-mirror, not necessarily current today — re-check the live GitHub issue before concluding a problem is still unresolved. ## Risks & Pitfalls - Windows is disproportionately represented in unresolved/recurring bugs in this mirror set (stdin deadlocks, Codex sandbox rejection, mojibake, IME focus loss) — self-hosters running the daemon on Windows should expect rougher edges than macOS/Linux. - Several "fixed" issues in the mirrors were later reported as recurring in the same thread (Windows Codex sandbox rejection, Codex-runtime comment attribution, OpenClaw process-exit) — a fix landing in one version does not guarantee the symptom is gone for good; check the specific version and, where possible, the live issue thread. - Do not conflate `queued` status with a broken daemon — it can simply mean no runtime has capacity yet (6 tasks/agent, 20 tasks/daemon by default) or the runtime is offline within its 2-hour grace window. - The "Usage shows zero" and "migration 103" playbooks are for the rollup pipeline specifically — running `SELECT rollup_task_usage_hourly();` by hand only fills one rollup and does not restore automatic scheduling if the scheduler itself is broken. - Don't treat this issue-status snapshot as a substitute for checking github.com/multica-ai/multica/issues directly — it reflects only what each mirror captured on 2026-08-10. ## Related Concepts - [[concepts/self-hosting]] — deployment steps and upgrade procedure referenced throughout the playbooks above. - [[concepts/configuration]] — environment variables (`FRONTEND_ORIGIN`, `CORS_ALLOWED_ORIGINS`, `COOKIE_DOMAIN`, local-directory resources) implicated in several recurring issues. - [[concepts/security-model]] — Windows Codex sandbox behavior referenced in the Windows-specific cluster above. - [[concepts/auth-and-tokens]] — email-delivery modes referenced in the verification-code playbook. - [[summaries/release-digest]] — which versions shipped the fixes cited above. ## Sources - raw/github_doc-apps-docs-content-docs-troubleshooting-mdx.md - raw/github_issue-bug-agent-invocation-fails-frequently.md - raw/github_issue-bug-creating-an-issue-through-an-agent-fails.md - raw/github_issue-bug-comment.md - raw/github_issue-bug-issue.md - raw/github_issue-bug-issue-comment-input-briefly-loses-focus-while-agents-loa.md - raw/github_issue-bug-codex-0-143-0-144-app-server-starts-but-multica-returns-.md - raw/github_issue-bug-agent-triggered-comments-can-be-stored-displayed-as-memb.md - raw/github_issue-how-to-debug-codex-returned-empty-output.md - raw/github_issue-bug-pi-agents-stuck-in-working-mode.md - raw/github_issue-openclaw.md - raw/github_issue-bug-turn-completed-tasks-idle-reaped-as-failed-empty-result-.md - raw/github_issue-bug-self-host-on-orbstack-tasks-wedge-in-queued-daemon-skips.md - raw/github_issue-bug-docker-compose-0-1-35.md - raw/github_issue-bug-the-request-has-been-blocked.md - raw/github_issue-chat-thread-does-not-auto-refresh-after-agent-responds-stuck.md - raw/github_issue-bug-self-host-session-is-not-stable.md - raw/github_issue-self-host-upgrade-note-v0-3-4-v0-3-5-requires-task-usage-bac.md - raw/github_issue-bug-attachment-download-not-working-on-desktop.md - raw/github_issue-bug-images-cannot-be-recognized-by-the-agent.md - raw/github_issue-rewriting-claude-md-on-every-run-discards-the-whole-prompt-c.md - raw/github_issue-cli-json-payloads-exhaust-agent-context-recent-n-is-ignored-.md - raw/github_issue-bug-the-agent-doesn-t-know-which-warehouse-to-choose.md - raw/github_issue-discussion-should-agents-bind-to-a-local-directory-or-stay-w.md - raw/github_issue-how-to-add-a-local-project-mapping.md - raw/github_issue-if-i-have-multiple-repos-how-does-the-agent-know-which-repo-.md - raw/github_issue-some-feedback.md - raw/github_issue-untitled.md - raw/github_issue-untitled-2.md - raw/github_issue-why-can-t-i-run-more-than-one-task-simultaneously-in-a-singl.md - raw/github_issue-ask-about-local-usage-issues.md - raw/github_issue-feature-claude-code.md - raw/github_issue-bug-timeline-filter-is-not-a-function.md - raw/github_issue-bug-desktop-app-fails-to-launch-after-updating-to-0-3-7.md - raw/github_issue-bug-issue-activity.md - raw/github_issue-feature-private-runtime.md - raw/github_issue-feature.md - raw/github_issue-feature-support-soft-delete-or-archive-issue.md - raw/github_issue-feature-register-multica-agent-as-a-dingtalk-bot.md <!-- ===== multica/wiki/concepts/vcs-integration.md ===== --> --- title: "VCS Integration" type: concept tags: [integrations, workflow, self-hosting] created: 2026-08-10 updated: 2026-08-10 sources: ["raw/github_doc-apps-docs-content-docs-vcs-integration-mdx.md", "raw/github_doc-apps-docs-content-docs-github-integration-mdx.md"] confidence: high multica_version: "v0.4.22" --- ## Definition VCS integration is how Multica links pull/merge requests to issues, mirrors CI status, and auto-completes issues on merge. GitHub is supported on both Multica Cloud and self-hosted deployments; self-hosted **Forgejo**, **Gitea**, and **GitLab** are supported only on self-hosted Multica, and a workspace can connect any combination of these providers alongside GitHub. Separately, and needing no provider configuration at all, agents open pull requests directly against a repository's own Git host using the daemon runtime's own Git credentials. ## How It Works **GitHub integration.** A workspace owner or admin opens **Settings → GitHub**, turns on the master switch, clicks **Connect GitHub**, and authorizes an account/organization and a set of repositories via GitHub's App install flow. The GitHub App only *reads* the authorized repositories' PR events — it never pushes commits, comments, or status checks. Three sub-switches control behavior: **PR sidebar** (show linked PRs on the issue), **Co-authored-by** (adds `Co-authored-by: multica-agent <github@multica.ai>` to agent commits), and **Auto-link PRs** (detect issue identifiers). A fourth item, **PR card → CI & mergeability**, pulls an authenticated GitHub API snapshot per linked PR to show CI status and mergeability, and requires `GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY` to be configured — without them, PRs still auto-link and merge-to-Done still works, just without the CI/mergeability display. **Self-hosted Git providers (Forgejo/Gitea/GitLab).** This section only appears once a server operator sets `MULTICA_VCS_INTEGRATION_ENABLED=true` and a `MULTICA_VCS_SECRET_KEY` (base64, 32 bytes) on a self-hosted deployment; it is not offered on Multica Cloud. Unlike GitHub's App model, each of these providers is connected per-workspace with an access token (Forgejo/Gitea: Settings → Applications; GitLab: a personal/group/project token with `read_api`) plus a registered webhook — both the token and webhook secret are encrypted at rest. Connecting shows a webhook URL and a webhook secret **once**; the operator manually registers the webhook on the repository/organisation/group in the provider's UI (Forgejo/Gitea: trigger on Pull Request + Commit Status; GitLab: Merge request events + Pipeline events). Every webhook delivery is authenticated against the stored secret. **Linking a PR to an issue.** Put the issue identifier (e.g. `MUL-123`) in the branch name or PR/MR title — matching is case-insensitive and scoped to the current workspace's issue prefix, and one PR can link to multiple issues. If the identifier only appears in the body, a GitHub-style close intent is required: `Closes MUL-123`, `Fixes MUL-123`, or `Resolves MUL-123` (self-hosted providers use the same closing-keyword convention). A reference-only mention like "Related to MUL-123" does not count as a working PR link, and commit messages / PR comments never trigger linking. **Merge-to-Done.** A merged PR only moves its issue to `Done` when *all* of these hold: (1) at least one merged linked PR used a close intent immediately followed by the identifier (`Closes login MUL-123`, with words in between, does not count); (2) the issue has no other working PR still `Open` or `Draft`; (3) the issue is not already `done` or `cancelled`. Titling or branching a PR with just `MUL-123` (no close intent) links it but never auto-completes the issue on its own, and a PR closed without merging never completes the issue. **What gets mirrored** on the issue's PR sidebar: repository, number, title, author, state (`Open`/`Draft`/`Merged`/`Closed`), added/deleted lines and changed-file count, CI status (all passed with a count, some failed naming the checks, or in-progress — "no checks configured" is never shown as passing), and mergeability (mergeable only on a clean GitHub-reported merge state, or conflicting/blocked/behind). If GitHub is briefly unreachable, the card keeps the last snapshot and marks it stale rather than going blank; merged/closed PRs stop showing CI or mergeability. **Agents opening PRs.** This needs no provider configuration in Multica at all: agents check out repositories inside the daemon runtime and push branches / open PRs using whatever Git credentials the runtime host already has (SSH deploy key, a token in the host's Git credential helper, etc.). Repository checkout works with any Git URL, so any provider works here even without a VCS integration connected. ## Key Parameters - `MULTICA_VCS_INTEGRATION_ENABLED` — self-hosted-only master switch for Forgejo/Gitea/GitLab; the section stays hidden until set `true`. - `MULTICA_VCS_SECRET_KEY` — base64-encoded 32-byte key encrypting self-hosted provider tokens and webhook secrets; required alongside the enable flag. - `MULTICA_PUBLIC_URL` — lets Multica show a ready-to-paste webhook URL for self-hosted providers; without it you must prepend your own origin to the shown webhook path. - `GITHUB_APP_SLUG`, `GITHUB_WEBHOOK_SECRET`, `FRONTEND_ORIGIN` — required for the GitHub connect button and webhook endpoint to work at all. - `GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY` — required only for the CI/mergeability snapshot; PR mirroring and merge-to-Done work without them. - Feature switches per GitHub workspace: GitHub integration (master), PR sidebar, Co-authored-by, Auto-link PRs. - Issue identifier format: `MUL-123`-style, workspace-prefix-scoped, case-insensitive match in branch/title; body mentions need a close-intent keyword. ## When To Use - Connect **GitHub** when repositories live on GitHub, for either Cloud or self-hosted deployments. - Connect **Forgejo/Gitea/GitLab** only on a self-hosted Multica deployment reaching an internal Git instance — this path does not exist on Cloud. - Rely on **agents opening PRs directly** whenever the goal is just "let the agent push code and open a PR" without needing PR-linking, CI mirroring, or merge-to-Done in Multica's UI. - Use a **close-intent keyword** (`Closes MUL-123`) whenever you want the issue to auto-complete on merge; a bare identifier in the title/branch is enough only to establish the link, not to close the issue. ## Risks & Pitfalls - A webhook secret (self-hosted providers) or App private key is shown/generated once — losing it means reconnecting. - `Closes login MUL-123` (words between the keyword and identifier) does **not** trigger merge-to-Done — the identifier must immediately follow the close-intent keyword. - A body-only mention without a close keyword (e.g. "Related to MUL-123") never shows as a working PR and never triggers Done. - Disconnecting GitHub in Multica does not uninstall the App on GitHub's side — new events stop flowing but the App keeps running until removed from GitHub's own installation settings. - Without `GITHUB_APP_ID`/`GITHUB_APP_PRIVATE_KEY`, the PR card silently shows no CI/merge state — this is a graceful degradation, not an error, and easy to mistake for a broken integration. - Mismatched webhook secrets between GitHub and the API produce `401 invalid signature` on every delivery. - "PR sidebar" off only hides the display block; it does not disconnect anything or stop mirroring underneath. ## Related Concepts - [[concepts/communication]] — comments and inbox notify on issue-status changes triggered by merges. - [[concepts/chat-integrations]] - [[concepts/self-hosting]] - [[concepts/configuration]] ## Sources - raw/github_doc-apps-docs-content-docs-vcs-integration-mdx.md - raw/github_doc-apps-docs-content-docs-github-integration-mdx.md <!-- ===== multica/wiki/entities/supported-agents-catalog.md ===== --> --- title: "Supported Agents Catalog" type: entity tags: [providers, agents, foundational, user, operator] multica_version: "v0.4.22" created: 2026-08-10 updated: 2026-08-10 sources: ["raw/github_doc-apps-docs-content-docs-providers-mdx.md", "raw/github_doc-apps-docs-content-docs-install-agent-runtime-mdx.md", "raw/github_doc-readme-md.md"] confidence: high --- ## Overview Multica markets itself as working with "20 agent CLIs" (README: *"Self-hostable, works with 20 agent CLIs, no lock-in"*) — external AI coding tool command-line programs it can drive as [[concepts/providers-and-runtimes]] runtimes, rather than a model or tool Multica ships itself. This page is the hub listing which tools are actually named in the docs, grounded in the "AI coding tools comparison" table (`providers.mdx`) and the install guide (`install-agent-runtime.mdx`), cross-checked against README's own claims. **On the "20" count — the docs do not enumerate a consistent set of exactly 20.** The `providers.mdx` comparison table and the `install-agent-runtime.mdx` install table both name **21 distinct tools**, including one — **Oh-My-Pi** (`omp`) — that does **not** appear in README's own "Runtimes" table or its "20 agent CLIs" bullet list. README's "Runtimes" table lists exactly 20 tools (matching its "20 agent CLIs" claim) but omits Oh-My-Pi. So: the fuller, doc-enumerated catalog is 21 tools; the "20" marketing figure appears to be the same list minus Oh-My-Pi. This is a discrepancy between two source documents, not a gap in this page — noted here rather than silently reconciled. ## Characteristics The table below reproduces `providers.mdx`'s comparison columns (detected command, session resumption, whether Multica can manage MCP for it, and its skill-injection path) plus the official install-guide link from `install-agent-runtime.mdx`. All 21 tools named in the docs are listed; none have been invented or inferred beyond what these two source pages state. "✓" reproduces the source table's checkmarks; "—" reproduces its dashes (meaning: not supported/not applicable). | Tool | Detected command | Session resumption | Multica-managed MCP | Skill injection path | Official install guide | |---|---|:---:|:---:|---|---| | Antigravity | `agy` | ✓ | — | `.agents/skills/` | [Antigravity install and sign-in](https://antigravity.google/docs/cli-install) | | Claude Code | `claude` | ✓ | ✓ | `.claude/skills/` | [Claude Code quickstart](https://code.claude.com/docs/en/quickstart) | | CodeBuddy | `codebuddy` | ✓ | ✓ | `.codebuddy/skills/` | [CodeBuddy quickstart](https://www.codebuddy.ai/docs/cli/quickstart) | | Codex | `codex` | ✓ | ✓ | `$CODEX_HOME/skills/` | [Codex CLI](https://developers.openai.com/codex/cli/) | | GitHub Copilot CLI | `copilot` | ✓ | — | `.github/skills/` | [Install Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli) | | Cursor Agent | `cursor-agent` | ✓ | ✓ | `.cursor/skills/` | [Install Cursor CLI](https://docs.cursor.com/en/cli/installation) | | DevEco Code | `deveco` | ✓ | — | `.deveco/skills/` | [DevEco Code](https://gitcode.com/openharmony-sig/deveco-code) | | Grok | `grok` | ✓ | ✓ | `.grok/skills/` | [Grok Build quickstart](https://docs.x.ai/build/overview) | | Hermes | `hermes` | ✓ | ✓ | per-task `HERMES_HOME/skills/` | [Hermes quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart/) | | Kimi CLI | `kimi` | ✓ | ✓ | `.kimi/skills/` | [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) | | Kiro CLI | `kiro-cli` | ✓ | ✓ | `.kiro/skills/` | [Install Kiro CLI](https://kiro.dev/docs/cli/installation/) | | OpenClaw | `openclaw` | ✓ | ✓ | `skills/` (task working directory) | [Install OpenClaw](https://docs.openclaw.ai/install) | | OpenCode | `opencode` | ✓ | ✓ | `.opencode/skills/` | [OpenCode quickstart](https://opencode.ai/en/docs) | | Pi | `pi` | ✓ | — | `.pi/skills/` | [Pi coding agent](https://github.com/earendil-works/pi) | | Oh-My-Pi | `omp` | ✓ | — | `.omp/skills/` | [Oh-My-Pi install](https://omp.sh) | | Qoder CLI | `qodercli` | ✓ | ✓ | `.qoder/skills/` | [Qoder CLI quickstart](https://docs.qoder.com/en/cli/quick-start) | | Qoder CN CLI | `qoderclicn` | ✓ | ✓ | `.qoder/skills/` | [Qoder CN CLI quickstart](https://help.aliyun.com/en/lingma/qodercli-cn/user-guide/qoder-cli-cn-get-started-quickly) | | Qwen Code | `qwen` | ✓ | ✓ | `.qwen/skills/` | [Qwen Code](https://github.com/QwenLM/qwen-code) | | QwenPaw | `qwenpaw` | ✓ | ✓ | per-task workspace `skills/` | [QwenPaw](https://github.com/agentscope-ai/QwenPaw) | | Reasonix | `reasonix` | ✓ | ✓ | `.reasonix/skills/` | [Reasonix](https://github.com/esengine/DeepSeek-Reasonix) | | Trae CLI | `traecli` | ✓ | ✓ | `.traecli/skills/` | [TRAE official site](https://www.trae.cn/) | Setup notes called out explicitly in the source docs: - **Reasonix** — run `reasonix setup` and configure a default provider and model before starting the daemon. - **QwenPaw** — choose the provider and model inside QwenPaw's own configuration; Multica's model picker for it is inert ("Managed by runtime") and an empty model list there is expected, not a sign the runtime is offline. - **Antigravity, GitHub Copilot CLI, DevEco Code, Pi** — do not read agent-level MCP configuration yet, so the MCP field isn't shown when creating agents bound to them. - **Codex** — uses a per-task `CODEX_HOME`; skills are never written into the system-level Codex directory. - **Hermes** — uses a per-task `HERMES_HOME`; this isolation only kicks in when the agent has skills bound, otherwise tasks use the machine's original Hermes home. - **Minimum versions** (from `install-agent-runtime.mdx`): Claude Code 2.0.0+, Codex 0.100.0+, Copilot 1.0.0+, Grok 0.2.89+, Qwen Code 0.20.0+ — below these, the daemon does not register the runtime. - "Supported" means Multica can invoke the CLI; it does not mean Multica supplies the tool's account, subscription, or model quota. ## How to Use To bring one of these tools online as a runtime (full detail in [[concepts/providers-and-runtimes]]): 1. Install the tool from its official guide (right-hand column above) — install only the tool(s) you intend to use, not all 21. 2. Launch it once in its own terminal and complete sign-in/model-provider setup (Reasonix: also run `reasonix setup`; QwenPaw: configure provider/model in QwenPaw itself). 3. Confirm the daemon's environment can see the command: ```bash command -v <command> <command> --version ``` On Windows PowerShell: ```powershell Get-Command <command> <command> --version ``` 4. Start or restart the daemon so it re-detects tools: ```bash multica daemon start multica daemon restart ``` 5. Open Multica's **Runtimes** page and confirm the tool shows online under the target computer — it's then selectable when creating or editing an agent. If nothing is detected, check tool sign-in first, then `command -v`/`Get-Command`, then `multica daemon logs -f` for version/path/auth errors, then restart the daemon, then recheck the Runtimes page. ## Related Entities No other entity pages exist yet in this wiki — this is the first. A natural future split would be one entity page per tool (or per protocol family) if any tool accumulates enough workspace-specific detail (troubleshooting history, version quirks) to outgrow this shared table. - [[concepts/providers-and-runtimes]] — the daemon/runtime mechanics this catalog feeds into, including custom runtime profiles built on the same protocol families. - [[concepts/agents]] — what actually gets bound to a runtime built on one of these tools. - [[concepts/creating-agents]] — where a tool's model/MCP/skill differences shape agent configuration choices. ## Sources - raw/github_doc-apps-docs-content-docs-providers-mdx.md - raw/github_doc-apps-docs-content-docs-install-agent-runtime-mdx.md - raw/github_doc-readme-md.md <!-- ===== multica/wiki/log.md ===== --> # Change Log ## 2026-08-10 — Initial build Built from the multica-ai/multica repo docs (English docs only — .ja/.ko/.zh variants excluded; vendored .repos excluded) + 30 release mirrors + ~60 issue mirrors. Multica is an open-source, self-hostable workspace for assigning issues to AI coding agents like teammates, written in Go. **Pages (25):** 23 concepts + 1 entity (supported-agents catalog) + 1 summary (release digest). **Sourcing notes:** - **Agent count discrepancy preserved**: the README claims "20 agent CLIs" and its Runtimes table lists 20, but the providers/install docs enumerate **21** distinct tools (README omits Oh-My-Pi). Documented verbatim in the supported-agents catalog rather than reconciled. The named set notably includes Hermes, Pi, and OpenClaw. - `troubleshooting` is grounded in the troubleshooting doc + issue mirrors with per-issue status (open / fixed / workaround / regressed) taken from each thread as of the 2026-08-10 mirror snapshot — not live GitHub. - Honest source correction: `SELF_HOSTING_AI.md` is an AI-agent-executable install runbook, not AI-provider config; described as written. - Newest stable release **v0.4.22**; digest covers v0.3.37→v0.4.22. - No XL tier yet (0.x, fast-moving). The provider matrix, self-hosting depth, and issue casebook are the natural XL seed as it stabilizes. <!-- ===== multica/wiki/summaries/release-digest.md ===== --> --- title: "Release Digest: v0.3.37 – v0.4.22" type: summary tags: [self-hosting, operator, developer, emerging] created: 2026-08-10 updated: 2026-08-10 sources: ["raw/github_release-v0-3-37.md", "raw/github_release-v0-3-38.md", "raw/github_release-v0-3-39.md", "raw/github_release-v0-3-40.md", "raw/github_release-v0-3-41.md", "raw/github_release-v0-3-42.md", "raw/github_release-v0-3-43.md", "raw/github_release-v0-4-0.md", "raw/github_release-v0-4-1.md", "raw/github_release-v0-4-10.md", "raw/github_release-v0-4-11.md", "raw/github_release-v0-4-12.md", "raw/github_release-v0-4-13.md", "raw/github_release-v0-4-14.md", "raw/github_release-v0-4-15.md", "raw/github_release-v0-4-16.md", "raw/github_release-v0-4-17.md", "raw/github_release-v0-4-18.md", "raw/github_release-v0-4-19.md", "raw/github_release-v0-4-2.md", "raw/github_release-v0-4-20.md", "raw/github_release-v0-4-21.md", "raw/github_release-v0-4-22.md", "raw/github_release-v0-4-3.md", "raw/github_release-v0-4-4.md", "raw/github_release-v0-4-5.md", "raw/github_release-v0-4-6.md", "raw/github_release-v0-4-7.md", "raw/github_release-v0-4-8.md", "raw/github_release-v0-4-9.md"] confidence: high multica_version: "v0.4.22" --- ## Key Points - The 30 mirrored releases span **v0.3.37 (2026-07-03) through v0.4.22 (2026-08-10, newest stable)** — 30 releases in 38 calendar days, close to one release per business day, with gaps consistently skipping weekends (e.g. 07-24 → 07-27, 07-31 → 08-03, 08-07 → 08-10) and two dates producing two same-day releases (2026-07-20: v0.4.5/v0.4.6; 2026-07-24: v0.4.10/v0.4.11). Each release mirror is a raw commit-message changelog, not prose notes. - This is unmistakably **pre-1.0, continuously-deployed software**: migration-numbering collisions recur across the entire window (v0.3.39, v0.3.42, v0.4.0's 161/162 prefix collision, v0.4.1, v0.4.10's 213/215 collision, v0.4.16's duplicate migration number, v0.4.22's channel-migration renumber), and shipping a feature/fix then reverting it *in the same or the very next release* is common rather than rare — it happens in at least 11 of the 30 mirrored releases (v0.3.39, v0.3.40, v0.3.42, v0.4.0, v0.4.1→v0.4.2, v0.4.8, v0.4.9 twice, v0.4.10→v0.4.11, v0.4.14→v0.4.15, v0.4.15→v0.4.19, v0.4.17, v0.4.18 twice). - **Licensing was still being actively clarified this late in the line**: v0.4.16 corrects a wrongly-declared Apache-2.0 SPDX tag on the Homebrew formula and introduces a distinct "Multica License" (verbatim Apache 2.0 text plus a UI-branding condition, later widened to all UI code with a NOTICE file — raw/github_release-v0-4-16.md); v0.4.17 adds explicit docs clarifying that free public hosting still requires a commercial license (raw/github_release-v0-4-17.md). - **New agent/runtime integrations land almost every release** across the 0.4.x line: DevEco Code (v0.4.1), Grok Build CLI (v0.4.2), Qwen Code (v0.4.7), Codex Fast mode (v0.4.9), Claude Opus 5 added to the runtime catalog (v0.4.11), Qoder CN CLI (v0.4.16), QwenPaw and Reasonix (v0.4.19), and oh-my-pi/omp (v0.4.22, the newest release) — a new backend or model roughly every 1–2 releases. - **Chat/bot channel integrations follow a consistent "add, then stabilize" pattern**: Lark/Feishu fixes recur across v0.4.2, v0.4.10, v0.4.12; DingTalk bot integration is added in v0.4.20 (flagged as community-maintained); WeCom (企业微信) smart-bot integration is added via the Channel engine in v0.4.21, immediately followed by a full release of WeCom hardening in v0.4.22 (duplicate-command handling, group slash commands, credential/handshake diagnostics, voice-note transcription, binding-token throttling, request-body caps). - **A cross-cutting daemon "runtime brief" rewrite effort** (rewriting the agent-facing injected instructions toward clearer, less contradictory judgment-form prompts) runs through nearly a dozen releases from v0.4.13 through v0.4.21, including a release that explicitly resolves "six injected-instruction contradictions" (v0.4.18). - **The 0.3.x → 0.4.0 transition marks a step change**, not just an increment: v0.3.x releases (v0.3.37–v0.3.43) read as an incremental fix/feature grab-bag (CLI ergonomics, runtime-picker refinements, a short-lived generic OpenAI-compatible LLM passthrough API added and removed within v0.3.42 itself), while v0.4.0 bundles a coordinated feature set — a UI "surface system" with unified settings/auto-save, a conversational agent-creation studio, a redesigned Skills/MCP capabilities UI, customizable keyboard shortcuts, and project start/due dates — alongside a cluster of migration-numbering collisions that needed reconciliation at the version boundary. - Security/auth fixes recur through the line: credential-redaction gaps for GitHub PATs and Google API keys (v0.4.0, v0.4.2), signed/scoped URLs for avatars and attachments on private buckets (v0.4.14), and an MCP-config-as-authoritative-allowlist change that was attempted and then reverted within v0.4.17 itself. - Self-hosting/deployment-relevant items are spread throughout: Helm affinity/tolerations (v0.4.3), automatic self-host upgrade migration backfill (v0.4.4), self-hosted Git providers Forgejo/Gitea/GitLab added and made self-host-only (v0.4.10), and a self-host daemon config-apply fix (v0.4.15) — see [[concepts/self-hosting]] and [[concepts/configuration]] for the operational detail these releases feed into. ## Relevant Concepts - [[concepts/self-hosting]] — the deployment guidance these releases' self-host-facing fixes (Helm, migrations, self-hosted Git providers) apply to. - [[concepts/configuration]] — the environment-variable surface some release items (e.g. self-host backend port unification in v0.4.16) touch directly. - [[concepts/troubleshooting]] — several fixes referenced here (byte-stable `CLAUDE.md`/prompt-cache fix in v0.4.13, Windows Codex sandbox default in v0.4.7 and v0.4.16, OrbStack RPC negotiation in v0.4.2) are the direct resolution of issues documented on that page. - [[concepts/security-model]] — v0.4.16's "remove the Linux Codex per-task HOME; default Linux to danger-full-access" item is the exact policy the security-model page describes. - [[concepts/auth-and-tokens]] — the v0.4.0/v0.4.2 credential-redaction fixes (GitHub PATs, Google API keys) protect the token types documented there. - [[concepts/multica-overview]] — the 20-agent-CLI roster this digest shows growing release-by-release. ## Source Metadata - **Type:** GitHub release notes, mirrored as raw commit-message changelogs (one file per version). - **Count:** 30 mirrors, versions v0.3.37 through v0.4.22 (newest stable). - **Date range:** 2026-07-03 (v0.3.37, published timestamp in mirror frontmatter) through 2026-08-10 (v0.4.22). - **Identifiers:** `raw/github_release-v0-3-37.md`, `raw/github_release-v0-3-38.md`, `raw/github_release-v0-3-39.md`, `raw/github_release-v0-3-40.md`, `raw/github_release-v0-3-41.md`, `raw/github_release-v0-3-42.md`, `raw/github_release-v0-3-43.md`, `raw/github_release-v0-4-0.md`, `raw/github_release-v0-4-1.md`, `raw/github_release-v0-4-2.md`, `raw/github_release-v0-4-3.md`, `raw/github_release-v0-4-4.md`, `raw/github_release-v0-4-5.md`, `raw/github_release-v0-4-6.md`, `raw/github_release-v0-4-7.md`, `raw/github_release-v0-4-8.md`, `raw/github_release-v0-4-9.md`, `raw/github_release-v0-4-10.md`, `raw/github_release-v0-4-11.md`, `raw/github_release-v0-4-12.md`, `raw/github_release-v0-4-13.md`, `raw/github_release-v0-4-14.md`, `raw/github_release-v0-4-15.md`, `raw/github_release-v0-4-16.md`, `raw/github_release-v0-4-17.md`, `raw/github_release-v0-4-18.md`, `raw/github_release-v0-4-19.md`, `raw/github_release-v0-4-20.md`, `raw/github_release-v0-4-21.md`, `raw/github_release-v0-4-22.md`. - **Source URLs:** `https://github.com/multica-ai/multica/releases/tag/<version>` for each file above.