Published by Dahshan Labs
Build and deploy portable AI agents with AgentMug
AgentMug represents an AI worker as a .agent file: a documented JSON format for its job definition. Developers can author that definition in code, validate it, and choose a supported runtime. Portability applies to the definition; tools, credentials, and execution support must be checked for each destination.
Start with the format and capability matrix
Read the .agent v1 specification and JSON Schema. The published capability matrix covers AgentMug Cloud and runtimeCore, the shared built-in baseline. It does not yet list the complete Desktop and CLI catalogs. Check the destination documentation and readiness checks too. A valid file alone does not prove the task will succeed.
Run locally or import into the cloud
The AgentMug CLI can run .agent files locally with your model keys. Use npx @agentmug/cli check <file> to inspect requirements without running the worker. For AgentMug Cloud, use the web import flow or authenticated import API. Import creates a worker ready to test, not proof of a successful run; review the preview and resolve missing connections and sources.
Choose the right deployment surface
Cloud uses AgentMug-managed model inference. Desktop and local CLI execution use your configured provider key or supported local endpoint. The .agent file is a definition; its host supplies model access, tool executors and source bindings. Exporting it does not turn a cloud-only tool into a local tool.
Connect through MCP when appropriate
There are two distinct paths. @agentmug/mcp-bridge forwards an MCP call to a hosted worker and needs a reachable host and key. The CLI's agentmug serve-mcp command exposes local .agent files and executes them through the CLI runtime. Local calls still need model access and supported tools; unattended approval-gated actions fail closed.
For local MCP, install the CLI with npm install -g @agentmug/cli. Set your MCP client's server command to agentmug and its arguments to serve-mcp followed by the absolute path to your .agent file or worker folder. Supply model credentials in that server's environment. This uses stdio; the documentation below describes the separate hosted bridge setup.
Validate outcomes, not just the file
Run a small task with representative data, inspect the tool results and output, and verify external effects in the destination system. Version the .agent definition in your repository and repeat those checks when changing tools, models, or requirements.
A first task you can test
A small example to try on your machine.
Download hello.agent into your working folder. It has no tools and requests a short text reply using Claude. Set ANTHROPIC_API_KEY in your terminal environment, then check requirements before running it. The CLI setup documentation shows the environment-variable command.
Download hello.agentCLI setup and commands
Example commands after saving hello.agent
npx @agentmug/cli check ./hello.agent
npx @agentmug/cli run ./hello.agent --input "Say hello in one sentence."The check command is read-only and reports missing setup. Once setup is complete, a successful run should return a short text reply. Verify the reply and process exit status yourself; the second command makes a model call and may incur provider charges.
Cloud, Desktop, CLI and MCP compared
| Option | Where execution happens and what to check |
|---|---|
| Cloud | AgentMug hosts execution and manages model inference. Connect your accounts in Cloud and check the worker's required tools and sources. |
| Desktop | Execution runs on your device with your configured model access. Local execution does not imply offline inference. Check supported platforms, tool support and source bindings. |
| CLI | Run locally from a terminal with your model access. Use check before run; recurring execution needs an external scheduler such as cron. Unattended approval-gated actions fail closed. |
| MCP | An integration path, not one execution host: mcp-bridge calls a hosted worker; CLI serve-mcp executes local files. The chosen host still supplies model access, tools and credentials. |
Frequently asked questions
- Is the .agent format open?
- The specification and JSON Schema are public, and @agentmug/runtime is licensed under Apache-2.0. This is AgentMug's own documented format, not a universal AI-agent standard. Check each separate package or service's license before use.
- Will every worker run on every surface?
- No. The file is portable, but tool support and credentials vary. Check the capability matrix and run the destination's readiness checks. A missing or unsupported capability must be resolved before relying on that worker.
- Can a coding assistant create a worker?
- Yes. Give it the official authoring skill, specification, and capability matrix. Validate the resulting .agent file and review the import preview before running it.
- Where should I start?
- Use the documentation for setup and examples, the specification for the file contract, and the capability matrix for supported tools. The business guide explains how to choose and test a useful first job.
References and next steps
- AgentMug documentation
- .agent format specification
- JSON Schema for .agent v1
- Supported tool capability matrix
- Official worker authoring skill
- Plans and pricing
- Explore workers
Continue with the other guide: Choose and test a business task