Skip to docs content
Browse documentation
On this page

The Minion factory map

Map Minion's discovery, credentials, integrations, packages, storage, schedules, events, inbox, hosted surfaces, memories and notes—and know where the boundary is.

Minion is a hosted factory for capabilities your assistant can discover, combine, and keep running. Your assistant connects to Minion over MCP and starts with two tools:

  • search finds capabilities, official guides, saved packages, notes, team skills and connected MCP servers' tools. Search before building so the assistant can reuse what you already have.
  • execute runs a temporary TypeScript module on Minion's servers. It can compose discovered capabilities, call connected services, and import exports from packages you own.

Those two doors lead to a set of team-isolated primitives.

What is on the factory floor

Secrets and integrations

Secrets are private credentials stored for your Minion team. Runtime code refers to them by a {{secret:name}} placeholder; Minion does not return the saved secret value to the assistant, and only sends it to hosts an owner or admin approved. See Secrets .

Integrations are saved OAuth connections to external services such as GitHub (including GitHub Apps) and Google. Their token bundles stay server-side and are refreshed there. Remote MCP servers expose their tools through Minion once an owner or admin approves them. Search shows the capabilities available to the signed-in team.

Packages, packageStorage() and sql()

Packages turn useful code into a named, versioned capability. Package source is a set of saved versions, edited in a repo session and published after checks pass; published code runs server-side in Minion's runtime. Packages belong to your team and are shared by every member and agent in it.

Each package gets isolated durable packageStorage() for runtime state such as cursors, preferences, and checkpoints, and its own SQLite database through sql() when you want rows to query. Source and versioned configuration belong in the package; credentials belong in secrets; changing runtime state belongs in packageStorage() or sql().

Jobs, workflows and schedules

Jobs run code later or on a schedule while your laptop is closed. A saved package declares recurring schedules in the jobs list of its minion block so the schedule travels with the package behavior. Deferred one-shot work uses minion.workflows.create({ runAt }). Job and workflow runs show up in the app (/app/jobs). See Jobs, workflows, and webhooks .

Apps, webhooks and events

Package apps give a package a hosted HTTP and browser surface at https://<team>.runminion.run/<package>/. They can render a small app, receive requests, and use the same package runtime and storage as its exports.

Webhooks give a package a secret, credentialed inbound URL. A provider sends an event to that URL, and Minion dispatches the validated request to the package export that owns it. Apps are general hosted request surfaces; webhooks are inbound event doors.

Events let a package react to things that happen inside Minion, such as a failed run or new mail, and emit its own topics. See Subscriptions and events .

Team inbox

Every team has an email address at {team-slug}@inbox.minion.codes. Mail is stored, treated as untrusted input, and can start a package. Your assistant can send mail to verified addresses. See Email primitives .

Memories, notes, tasks and skills

Memories are durable facts and preferences attached to your Minion team. Search retrieves relevant memories as context for a task. Memory is for information worth carrying between conversations and between agents, not package state, source configuration, or credentials. See Shared memory .

Notes hold longer working documents, plans and handoffs. Tasks are a shared todo list. Team skills are playbooks your team publishes for every connected agent.

The boundary around the factory

Hosted Minion cannot see your Mac's disk, your local Obsidian vault, local-only CLI processes, localhost, or devices reachable only on your home network. Installing a desktop MCP server does not make it reachable from Minion's Cloudflare Workers.

To bring a local capability into the factory, run an MCP server beside the local resource and expose that server through a protected public HTTPS route. The home MCP guide describes the Cloudflare Tunnel and Access pattern and points at home-mcp-starter . Then connect its URL as a remote MCP server . Search ranks the server's tools; search({ entities: ["mcp-server:<name>"] }) lists them.

Work that does not fit a Worker isolate — a large npm graph, native code, or multi-minute CPU — follows the same split: the saved package orchestrates, and the owner operates the process. See Offload work that does not fit a Worker isolate .

A practical route through the map

  1. Search for the outcome and inspect the exact capability shape.
  2. Connect the needed secret, integration, or remote MCP server.
  3. Use execute for a one-off composition and authenticated smoke test.
  4. Author a package when the behavior should be reusable, reviewed, or scheduled.
  5. Keep runtime state in packageStorage() or sql() and expose only the app, webhook, export, or job surfaces the package needs. A package lock can pin reviewed code, but it cannot narrow a provider token. For Gmail draft and send permission limits, see ( Gmail drafts and send permissions ).
  6. Save a memory only when the user wants Minion to retain a durable fact or preference.

For the full ask-once-to-package loop, continue with How Minion works . When packages, integrations, and MCP servers look interchangeable, read Packages, integrations, and MCP servers . For package implementation details, load the package authoring guide .