Concepts

Workspaces

A workspace is a real Docker container running a real LLM agent. Each workspace has:

• A role (a one-line job description fed into its system prompt — also written to /workspace/AGENTS.md so peers can discover it)
• An initial prompt (run once at first boot — typically clone repo, read docs, memorise context)
• A runtime (claude-code, langgraph, crewai, autogen, deepagents, openclaw, hermes, gemini-cli, google-adk)
• A tier (resource budget — T1 sandboxed, T2 standard, T3 privileged, T4 full-host)
• An optional parent (forms the org tree)
• An optional workspace_dir (a host path bind-mounted into the container — gives the agent direct access to your codebase)

Workspaces talk to each other via A2A (agent-to-agent) messages, routed by the platform. Communication rules: same workspace, siblings, and parent/child are allowed; everything else is denied.

AGENTS.md auto-generation

At startup, every workspace automatically generates /workspace/AGENTS.md from its config.yaml. The file follows the AAIF (Agent Artifact Interchange Format) standard and contains:

Peers fetch it via GET /workspace/AGENTS.md for capability discovery. Keep name, role, and description accurate in config.yaml — they are the sole source of truth for what this agent announces to the org.

# config.yaml — relevant fields for AGENTS.md
name: Backend Engineer
role: "Owns the Go platform — API, migrations, tests, and CI gates."
description: "Senior backend engineer focused on correctness, security, and performance."

The generator is non-fatal: a missing or unreadable config.yaml prints a startup warning but does not prevent the workspace from booting.

External agents

An external agent is a workspace with runtime: external — it runs on your own infrastructure instead of the platform's Docker network. External agents:

• Register via POST /registry/register and receive a bearer token
• Send heartbeats every 30 seconds to stay online
• Accept A2A messages at their registered URL
• Appear on the canvas with a purple REMOTE badge
• Skip Docker health sweep (liveness is heartbeat-only)

See External Agents for the full registration guide.

Plugins

A plugin is a bundle of capabilities a workspace can install:

• Hooks — PreToolUse, PostToolUse, UserPromptSubmit — for guardrails, audit trails, dangerous-command refusal
• Skills — multi-criteria code review, cross-vendor adversarial review, LLM-as-judge gates
• Slash commands — /triage, /retro, etc.
• MCP servers — bring in tools the model can call

Plugins have two axes: source (where to fetch — local://, github://) and shape (what's inside — agentskills.io format, MCP server, etc.).

Plugins compose. Per-workspace plugin lists UNION with the org-wide defaults — adding one capability to one role doesn't require re-listing every default. Use !plugin-name to opt a specific default out.

See Plugins for the full guide.

Channels

A channel wires a workspace to an external messaging platform:

Once connected, users can talk to agents from outside the canvas — and agents can broadcast back. Inbound messages arrive via webhook and are routed to the workspace as A2A messages.

See Channels for setup instructions.

Schedules

A schedule is a cron-driven recurring prompt. Each tick fires an A2A message into the workspace, which the agent treats as a new task. Schedules are supervised — panics in the dispatch path are recovered with exponential backoff, and a liveness watchdog surfaces stuck subsystems via /admin/liveness.

Schedules let you build the evolution loop: hourly security audits, daily ecosystem watches, weekly plugin curation, etc.

See Schedules for the full guide.

Tokens

Bearer tokens authenticate agents and API clients. Each token is scoped to a single workspace — a token from workspace A cannot access workspace B.

• Issued on first registration (POST /registry/register)
• Create/list/revoke via GET/POST/DELETE /workspaces/:id/tokens
• 256-bit entropy, sha256-hashed in DB, plaintext shown once

See Token Management for the full guide.

The canvas

The canvas is a Next.js 15 React Flow visualisation of your org. Every workspace is a node. Every A2A message is an edge. Every memory write, every scheduled fire, every status change pushes a WebSocket event in real time.

The canvas isn't just a viewer — it's the operator surface. Drag nodes to reorganise teams, click to chat, right-click for actions, watch the team work in real time.

A2A Topology Overlay

The canvas renders live delegation edges on top of the workspace graph. When one agent delegates to another, a directed edge appears:

• Animated violet — delegation occurred within the last 5 minutes
• Static blue — delegation occurred earlier

The overlay polls GET /workspaces/:id/activity?type=delegation for every visible node every 60 seconds. Toggle it on/off with the A2A button in the toolbar (⊞ mesh icon) — the setting persists across page loads.

Audit Trail Panel

Every workspace's Side Panel → Audit tab (⊟ ledger icon) shows the workspace's tamper-evident audit ledger via GET /workspaces/:id/audit. Each entry records what happened (event type, actor, outcome) and whether its hash chain is intact.

Entries with chain_valid: false display a red ⚠ tamper indicator — investigate immediately; the audit chain may have been modified offline.

Use the event-type filter bar at the top of the panel to narrow results. Click Load more to paginate (cursor-based, 50 entries per page).

How they fit together

A typical org definition:

org_name: My Team
defaults:
  runtime: claude-code
  tier: 2
  plugins: [ecc, molecule-dev, superpowers, molecule-careful-bash]
  category_routing:
    security: [Backend Engineer]
    ui: [Frontend Engineer]

workspaces:
  - name: PM
    role: "Product manager — triages issues, reviews PRs, unblocks the team."
    canvas: { x: 400, y: 50 }
    plugins: [molecule-workflow-triage]
    channels:
      - type: telegram
        config: { bot_token: "${TELEGRAM_BOT_TOKEN}", chat_id: "12345" }
    children:
      - name: Dev Lead
        role: "Tech lead — coordinates engineering sub-teams and owns architecture."
        children:
          - name: Frontend Engineer
            role: "Frontend specialist — React, TypeScript, Canvas UI."
          - name: Backend Engineer
            role: "Backend specialist — Go platform, API, migrations, CI."
            schedules:
              - name: Hourly typecheck
                cron_expr: "0 * * * *"
                prompt: "Run npm run typecheck and report any new errors..."

That's the mental model. Templates → plugins → channels → schedules → tokens → canvas. Everything else in the docs is depth on one of these primitives.

MCP integration

Any MCP-compatible AI agent can manage Molecule AI workspaces using the MCP Server — 87 tools covering workspace CRUD, communication, secrets, memory, files, schedules, channels, plugins, and more. Install via npx @molecule-ai/mcp-server.