# Minion > Memory, keys, code and jobs for every agent you use. Each page below is available as raw Markdown at https://minion.codes/docs/.md. ## Guides - [What is Minion?](https://minion.codes/docs/what-is-minion.md): 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](https://minion.codes/docs/agent-inbox.md): 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](https://minion.codes/docs/local-mcp-tunnels.md): 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](https://minion.codes/docs/connect-your-agent.md): 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](https://minion.codes/docs/first-win.md): 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](https://minion.codes/docs/account-package-invocation-token-setup.md): 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](https://minion.codes/docs/quick-example.md): 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](https://minion.codes/docs/onboarding.md): 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](https://minion.codes/docs/flake-hunter.md): 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](https://minion.codes/docs/locked-gmail-drafts.md): 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](https://minion.codes/docs/google-oauth.md): 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](https://minion.codes/docs/how-minion-works.md): 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](https://minion.codes/docs/integration-bootstrap.md): 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](https://minion.codes/docs/triggers.md): 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](https://minion.codes/docs/locked-mcp-server.md): 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](https://minion.codes/docs/oauth.md): 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](https://minion.codes/docs/heavy-work-offload.md): 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](https://minion.codes/docs/openapi-integrations.md): 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](https://minion.codes/docs/packages-integrations-mcp.md): 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](https://minion.codes/docs/values.md): Where named state belongs in Minion: memories, package storage, notes, secrets or integrations. - [Purchase thanks](https://minion.codes/docs/purchase-thanks.md): 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](https://minion.codes/docs/platform-efficiency.md): 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](https://minion.codes/docs/search-and-execute.md): 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](https://minion.codes/docs/portability.md): Second-agent proof after a first win. Find what the account already has, reuse it once, and stop. - [Secret setup](https://minion.codes/docs/account-secret-setup.md): 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](https://minion.codes/docs/secret-backed-integration.md): 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](https://minion.codes/docs/secrets.md): 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](https://minion.codes/docs/sentry-issues.md): 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](https://minion.codes/docs/memory.md): 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](https://minion.codes/docs/text-your-agent.md): 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](https://minion.codes/docs/minion-factory.md): Map Minion's discovery, credentials, integrations, packages, storage, schedules, events, inbox, hosted surfaces, memories and notes—and know where the boundary is. ## Packages - [Packages](https://minion.codes/docs/packages.md) - [Package manifest](https://minion.codes/docs/package-manifest.md): 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](https://minion.codes/docs/repo-sessions.md): 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](https://minion.codes/docs/package-apps.md): Serve a Hono app from a package at https://.runminion.run//: the minion.app block, members or public access, how members sign in, limits and the security model. - [Package authoring](https://minion.codes/docs/package-authoring.md): 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](https://minion.codes/docs/package-lifecycle.md): 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](https://minion.codes/docs/package-storage.md): 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](https://minion.codes/docs/package-subscriptions.md): 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](https://minion.codes/docs/repos.md): Minion has no plain repos or git remotes. Package source lives in saved versions: edit it with repo sessions or packages.save. - [Sharing packages](https://minion.codes/docs/community-packages.md): 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 a provider](https://minion.codes/docs/connect.md): Connect GitHub, Google, Slack, Notion and other providers to Minion once, then use them from every agent without exposing the token. - [Connect Discord](https://minion.codes/docs/connect-discord.md): 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](https://minion.codes/docs/connect-figma.md): 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](https://minion.codes/docs/connect-github.md): 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](https://minion.codes/docs/connect-google.md): 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](https://minion.codes/docs/connect-notion.md): 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](https://minion.codes/docs/connect-origin.md): 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](https://minion.codes/docs/connect-salesforce.md): 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](https://minion.codes/docs/connect-slack.md): 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](https://minion.codes/docs/connect-spotify.md): 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. ## Using Minion - [Activity](https://minion.codes/docs/activity.md): 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](https://minion.codes/docs/mcp-client-servers.md): 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](https://minion.codes/docs/connect-your-agent-use.md) - [Email primitives](https://minion.codes/docs/email-primitives.md): 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](https://minion.codes/docs/execute.md): How execute runs your code: module shape, imports, params, what comes back, limits, idempotency, packages, storage and authenticated fetch. - [First steps](https://minion.codes/docs/first-steps.md) - [Inbound webhooks](https://minion.codes/docs/webhooks.md): 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](https://minion.codes/docs/memory-use.md) - [Minion Community Project mark](https://minion.codes/docs/community-project-mark.md) - [Mutating actions and confirmations](https://minion.codes/docs/mutating-actions.md) - [Needs attention](https://minion.codes/docs/waiting.md): 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](https://minion.codes/docs/privacy.md) - [Raw MCP content blocks](https://minion.codes/docs/raw-content-blocks.md): Execute returns one JSON text block with runId, result and logs. Returning raw MCP content blocks such as images isn't supported yet. - [Search](https://minion.codes/docs/search.md) - [Secrets and host approval](https://minion.codes/docs/secrets-and-values.md) - [Synthetic event dispatch](https://minion.codes/docs/synthetic-event-dispatch.md): 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](https://minion.codes/docs/tasks.md): 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](https://minion.codes/docs/troubleshooting.md) - [Using Minion](https://minion.codes/docs/using-minion.md) - [What can Minion do?](https://minion.codes/docs/what-can-minion-do.md) - [Workflows](https://minion.codes/docs/workflows.md): Run a package export once in the background: now, at a set time, or for longer than execute allows. ## Principles - [Engineering principles](https://minion.codes/docs/principles.md): The short rules Minion is built by, and what each one means for the packages you write. - [Delete what is off the common path](https://minion.codes/docs/principle-common-path.md): The common path is the one the product takes. Options, fields and branches that exist only for other paths get deleted. - [Examples over prose](https://minion.codes/docs/principle-examples-over-prose.md): 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](https://minion.codes/docs/principle-fail-loudly.md): Fail where the code can still name the mistake and refuse the bad write, not later behind a quiet fallback. - [Finish the migration](https://minion.codes/docs/principle-cleanup.md): When a new way replaces an old one, the work isn't done until the old way is gone. - [Fix the root bottleneck](https://minion.codes/docs/principle-root-bottleneck.md): Fix what makes something slow instead of hiding it with longer timeouts, retries or a degraded mode. - [Generic platform](https://minion.codes/docs/principle-generic-platform.md): Minion exposes generic primitives. Vendors and frameworks are configuration or ordinary dependencies, not platform branches. - [Keep agent context lean](https://minion.codes/docs/principle-lean-agent-context.md): Agents load guidance on demand. Keep the entry point tiny and put detail one step away. - [No test-only code in production](https://minion.codes/docs/principle-no-test-only-code.md): If every test were deleted, production would still keep the code. Test seams that fail that check don't belong. - [One source of truth](https://minion.codes/docs/principle-source-of-truth.md): Keep each fact in one record. Anything derived from it is a cache, and the write path refreshes that cache. - [Test the workflow](https://minion.codes/docs/principle-test-the-workflow.md): 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](https://minion.codes/docs/principle-two-way-doors.md): Ship cheap, reversible changes quickly. Spend the review on changes that are expensive or impossible to undo.