AgentMug · 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. Use the published capability matrix to select tools supported on your target surface. A syntactically valid file is not enough to prove that a worker can complete its task with the available accounts and tools.
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.
Run locally or import into the cloud
The AgentMug CLI can run .agent files locally with your model keys. Use agentmug check <file> to inspect requirements before a run. To move into AgentMug Cloud, use the web import flow or the authenticated import API. Review the import preview and resolve blockers before executing.
Choose the right deployment surface
Desktop is useful for local work; CLI fits terminal workflows; AgentMug Cloud provides a managed execution surface. A cloud-only tool will not become a local tool merely by exporting the file. Check the capability matrix and the destination's connection requirements when moving between surfaces.
Connect through MCP when appropriate
The AgentMug MCP bridge lets an MCP client call workers through AgentMug Cloud. The bridge is a connection to the cloud service and requires its configuration and credentials. It is not an offline replacement for the runtime. See the documentation for the current setup instructions.
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.
Frequently asked questions
- Is the .agent format open?
- The format specification and JSON Schema are publicly available. The @agentmug/runtime npm package is published under Apache-2.0. Check the license of each separate package or service 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.