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.

Related documentation

Author and validate the worker

The @agentmug/runtime package exports buildAgentFile(), parseAgentFile(), and serializeAgentFile(). Use them to construct, validate, and serialize a definition. Keep credentials outside the file, declare the connections it requires, and use the official authoring skill when a coding assistant generates the definition.

Related documentation

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.

Related documentation

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.

Related documentation

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.

Related documentation

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.

Related documentation

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

OptionWhere 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.

Related documentation

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.

Related documentation

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.

Related documentation

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.

Related documentation

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

Continue with the other guide: Choose and test a business task