Minion docs

What is Minion?

Start here. Minion is the home your agents share — connect the AI agent you already use over MCP and it gains durable memory, secrets it never reads, saved packages, and jobs that keep running while you are offline. Covers what Minion is and is not, what you cannot get elsewhere, the building blocks, real uses, and notes for an agent running a discovery interview. Nothing here requires an account.

Agent inbox

Every team has an email address at inbox.minion.codes. Mail sent there is stored, checked for spoofing, and readable by your agents through minion.email.* and the Inbox page. Load this when someone asks how the inbox works or how to give an agent an email address.

Connect a home MCP server

Run an MCP server next to a vault, CLI or device, publish it with Cloudflare Tunnel, and add it to Minion with a bearer token.

Connect your agent

The three-step Get started flow for people: connect the agent you already use over MCP, paste one prompt so that agent makes something useful in your account, then connect a second agent from another ecosystem and watch it reuse the same memory and package. Includes what approving access means, verified-email requirements, and which agents suit building versus using.

Email and memories: the welcome-email loop

Optional agent playbook: send a welcome email, point the person at their own inbox to reply, look the reply up when they say it is sent, save what matters as memories, then offer a next step. The default first build is quick-example; the in-app Get started page is /app/onboarding. Includes the no-polling rule and troubleshooting for missing mail and unbound tools.

External HTTP knock

Call a package export over HTTP with inbound webhooks. One webhook name binds one export; mint a handle with webhooks.mint, register GitHub hooks with webhooks.apply, and POST JSON.

First build: ad hoc execute, then persist

Agent playbook after Say hello on the Get started page (/app/onboarding): run one useful ad hoc execute, show the result, persist that working code as a package they own, and offer optional triggers without recommending one.

First run: the onboarding briefing

First-run guide for a connected agent. Teach lightly what Minion is and is not, offer six concrete first-win choices, help them take one small win from their pick, and set up integrations with clear difficulty. Then Step 3.

Flake Hunter

A worked cron example: a package-owned daily job that scans CI for flaky end-to-end runs, stays quiet on a clean day, and only emails you when a flake signal is present. Load this when someone asks how to hang a schedule on a package they own.

Gmail drafts and send permissions

Google has gmail.send but no drafts-only scope. gmail.compose can manage drafts and send. Publish a drafts-only package, lock it, then integrationLock the connection so execute cannot use the token.

Google OAuth walkthrough

A walkthrough of Google OAuth for Gmail inbox reading: official guides first, one console step at a time, the Google preset on the Integrations page, no secrets in chat, then a Gmail profile smoke test.

How Minion works

The factory loop as a conversation: ask what your favorite bot shipped, save the answer as an export you can invoke from any agent, then a daily email that stays quiet until something actually ships.

Integration bootstrap

START HERE when a third-party integration must work before saving a dependent package or package app: inspect integration and secret state, stop for setup, run an authenticated smoke test, then build a thin helpers package.

Jobs, workflows, and webhooks

How work runs when nobody is in the chat. Package-owned jobs for recurring schedules, workflows for deferred or long one-shot runs, inbound webhooks for provider events, subscriptions for events inside Minion, and the inbox — which to pick, how each is declared, and how to test one safely before enabling it. Load this when someone asks how to run something later, on a schedule, or when a provider knocks.

Lock an MCP server to a package

A connected MCP server exposes every approved tool to execute and every package. Lock the server to saved packages, and put the calls you want in a thin wrapper package.

OAuth: bring your own app

START HERE for third-party OAuth: register an OAuth app on the Integrations page, the exact redirect URI (https://app.minion.codes/oauth/callback), GitHub and Google presets, custom providers, token refresh, and how it differs from MCP OAuth.

Offload heavy work

The sandbox imports only zod and hono, with 128 MB and 20 s CPU per run. Run PDF parsing, browsers and big libraries in a service you operate.

OpenAPI integrations

Call a third-party API that publishes an OpenAPI document: treat the spec as untrusted, authenticate with an integration or secret, and wrap the operations you need in a thin helpers package.

Packages, integrations, and MCP servers

Packages are saved behavior. Integrations are account-owned logins. MCP servers are how agents connect. Use this when those three look interchangeable.

Persist named state

Where named state belongs in Minion: memories, package storage, notes, secrets or integrations.

Purchase thanks

A worked event example: a verified purchase becomes a fact your factory already knows, and a package drafts a thank-you without anyone typing. Load this when someone asks how to react to an event a package you own already emitted.

Runtime and limits

How Minion runs your code in a fresh isolate, what each surface counts against on your plan, the monthly worker compute include and prepaid credits, and the per-run limits for time, memory and results.

Search and execute

Minion's MCP surface is two tools. search finds capabilities, guides, packages, notes, team skills and connected MCP server tools. execute runs an ephemeral module that calls what you found. Covers how they work together and the inputs an agent actually passes.

Second agent: reuse what already exists

Second-agent proof after a first win. Find what the account already has, reuse it once, and stop.

Secret setup

How to get an API key or PAT into Minion: the Secrets page form, its fields, approval reminders, and what an agent should say and wait for.

Secret-backed integrations

Default non-OAuth recipe for secret-backed integrations: research auth, collect secrets on the Secrets page, approve hosts, run a smoke test, then build the downstream package.

Secrets

How Minion lets your agent use your API keys, tokens, and private keys without ever reading them: no capability returns a value, {{secret:name}} placeholders resolved at the network boundary, host approval, expiry, and where each kind of credential lives. Load this when someone asks how credentials work or whether the agent can see a key.

Sentry Issues

A worked webhook example: a package-owned inbound URL that accepts a Sentry issue POST, verifies HMAC on the platform, and starts triage without a model in the request path. Load this when someone asks how to hang a vendor webhook on a package they own.

Shared memory

What a Minion memory is, why it lives on the account instead of in one host's chat, how memories surface automatically on search and execute, the verify-first rule for writes, and what does not belong in memory (package state, config, credentials). Load this when someone asks what their agents remember about them or how memory travels between agents.

Text your agent

How to let a spouse or friend talk to your agent over a familiar chat surface (iMessage worked example). Surface vs brain vs tools: the agent holds the conversation; Minion is memory, secrets, packages, and jobs, not the chat buddy. Covers OpenClaw, Hermes Agent and Bezalel patterns, a simpler SMS path through a webhook, and email through the team inbox.

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.

Packages

Package manifest

Every field of a package's package.json: name, exports and the minion block (description, tags, dependencies, jobs, subscriptions, emits, webhooks, app), with the rules each save is checked against.

Editing package source

Open a repo session on a saved package, edit files one at a time or with a patch, run the publish checks, then publish a new version.

Package apps

Serve a Hono app from a package at https://<org>.runminion.run/<package>/: the minion.app block, members or public access, how members sign in, limits and the security model.

Package authoring

START HERE when creating or materially changing a Minion package: package shape, required README.md (human) and AGENTS.md (agent), README Intent section, per-export JSDoc (search Purpose), personal-details hygiene before going public, secret-using package approval checklist, and scope-update guidance without adding new primitives.

Package lifecycle: reuse, execute, or create

Choose between invoking existing behavior, temporary execute exploration, deferred workflows, and creating a durable saved package; test package-owned job wrappers safely.

Package storage and SQL

Saved packages keep durable state with packageStorage() (JSON key/value per package) and sql() (a SQLite database per package). Limits, isolation, moving from Postgres, and how storage counts against your plan.

Package subscriptions and events

Run a package export when a platform topic fires (failed runs, jobs, OAuth, webhooks, inbox mail) or another package emits one. Test and inspect deliveries.

Plain repos

Minion has no plain repos or git remotes. Package source lives in saved versions: edit it with repo sessions or packages.save.

Sharing packages

Minion has no public package catalog yet. How to reuse packages inside your organization, and what to do when you need one somewhere else.

Connect a provider

Connect GitHub, Google, Slack, Notion and other providers to Minion once, then use them from every agent without exposing the token.

Connect Discord

Connect Discord to Minion with a bot token for channels or a custom OAuth app for your identity, and see what Minion can't receive yet.

Connect Figma

Connect Figma to Minion with a personal access token or a custom OAuth app, then read files and comments from api.figma.com.

Connect GitHub

Connect GitHub to Minion with your own OAuth App or a fine-grained token, then call the GitHub API from execute and packages.

Connect Google

Connect Google Calendar, Gmail and Drive to Minion with your own OAuth client, avoid the 7-day Testing trap, and call the APIs.

Connect Notion

Connect Notion to Minion with an internal connection token or a custom OAuth app, then read and write shared pages from execute and packages.

Connect Origin

Connect Origin to Minion by signing app JWTs with secrets.jwtSign and minting short-lived installation tokens per run, or try the API with a single token stored as a secret.

Connect Salesforce

Add Salesforce to Minion as a custom OAuth app, allow your My Domain host with a wildcard, and run SOQL from execute or a package.

Connect Slack

Connect Slack to Minion with a bot token or a user-token OAuth app, call the Web API, and receive Slack events through a package webhook.

Connect Spotify

Add Spotify to Minion as a custom PKCE OAuth app, connect it, and call the Web API from execute or a package without handling tokens.

Activity

Where to see what ran and what failed: the Runs page, the minion.runs.* capabilities, and how to triage or react to errors.

Connect remote MCP servers to Minion

Add a remote MCP server (bearer token or OAuth), approve its tools, call them as minion.mcp[name].tool(args), and lock a server to saved packages.

Connect your agent

Email primitives

Reference for the team inbox: addressing, the minion.email.* capabilities, plan limits, sender rules and spoofing checks, and the reply/send rules that keep Minion from being an open relay.

Execute

How execute runs your code: module shape, imports, params, what comes back, limits, idempotency, packages, storage and authenticated fetch.

First steps

Inbound webhooks

Give a package a secret URL that GitHub, Stripe, Sentry or Slack can call: declare it, mint it, verify signatures, test it and debug deliveries.

Memory and conversation context

Minion Community Project mark

Mutating actions and confirmations

Needs attention

The Waiting page and minion.waiting.list: what only a person can clear (approvals, reconnects, expiring secrets, failing jobs) and the link to clear each one.

Privacy

Raw MCP content blocks

Execute returns one JSON text block with runId, result and logs. Returning raw MCP content blocks such as images isn't supported yet.

Search

Secrets and host approval

Synthetic event dispatch

Owners and admins run one package's subscription handler right away with minion.events.dispatchSynthetic to check it after publishing. A real run with real side effects; filters are skipped and the envelope carries synthetic: true.

Tasks

Manage a shared team todo list and board from the dashboard, connected agents, and REST API, with tags, priorities, start and due dates, reminders, progress comments, and filters.

Troubleshooting

Using Minion

What can Minion do?

Workflows

Run a package export once in the background: now, at a set time, or for longer than execute allows.

Engineering principles

The short rules Minion is built by, and what each one means for the packages you write.

Delete what is off the common path

The common path is the one the product takes. Options, fields and branches that exist only for other paths get deleted.

Examples over prose

Show one example that matches the current code. When a procedure has several steps, make it a script or a package.

Fail loudly at the right layer

Fail where the code can still name the mistake and refuse the bad write, not later behind a quiet fallback.

Finish the migration

When a new way replaces an old one, the work isn't done until the old way is gone.

Fix the root bottleneck

Fix what makes something slow instead of hiding it with longer timeouts, retries or a degraded mode.

Generic platform

Minion exposes generic primitives. Vendors and frameworks are configuration or ordinary dependencies, not platform branches.

Keep agent context lean

Agents load guidance on demand. Keep the entry point tiny and put detail one step away.

No test-only code in production

If every test were deleted, production would still keep the code. Test seams that fail that check don't belong.

One source of truth

Keep each fact in one record. Anything derived from it is a cache, and the write path refreshes that cache.

Test the workflow

One test covers one workflow: the setup, the actions, and assertions checked against something the code doesn't share.

Two-way and one-way doors

Ship cheap, reversible changes quickly. Spend the review on changes that are expensive or impossible to undo.