Mech Server

A CLI to create, deploy and manage Mechs — AI agents that execute tasks on-chain for payment — on the Olas Marketplace.

Note: The codebase uses the term service (from the underlying Open Autonomy framework) interchangeably with AI agent.

Quick Start

pip install mech-server
mech setup -c <chain>
mech run -c <chain>

Supported Chains

Requirements

• Python >=3.10, <3.12
• Docker Engine + Docker Compose

Commands

Developing a new tool

New service (no existing mech)

1. Set up the workspace and deploy the mech on-chain:

   mech setup -c <chain>
   

2. Scaffold a tool:

   mech add-tool <author> <tool_name> -d "Tool description"
   

3. Implement the tool logic in ~/.operate-mech/packages/<author>/customs/<tool_name>/<tool_name>.py. The scaffold generates a working stub with the correct structure:

   ALLOWED_TOOLS = ["tool_name"]
   
   def run(**kwargs: Any) -> MechResponse:
       prompt = kwargs.get("prompt")
       if prompt is None:
           return error_response("No prompt has been given.")
       result = do_work(prompt)
       context = None
       artifact = None
       callback = None
       return result, prompt, context, artifact, callback
   

4. If your tool requires API keys or other secrets, add them to ~/.operate-mech/.env.

5. (Optional) If your mech should serve off-chain requests over HTTP, provide a URL that routes to the mech's HTTP server (localhost:8000). This URL is included in the mech's on-chain metadata so that clients can discover it:

   mech prepare-metadata --name <name> -c <chain> --offchain-url <url>
   

   Alternatively, set MECH_OFFCHAIN_URL in ~/.operate-mech/.env.<chain> and run prepare-metadata without the flag.

6. Generate and publish metadata (to IPFS), then update the on-chain registry. --name is the human-readable mech name and is required:

   mech prepare-metadata --name <name> -c <chain>
   mech update-metadata -c <chain>
   

7. Run:

   mech run -c <chain>
   

Existing service (mech already running)

1. Stop the service:

   mech stop -c <chain>
   

2. Scaffold, implement, and set any required API keys (same as steps 2–4 above).

3. Generate and publish metadata (to IPFS), then update:

   mech prepare-metadata --name <name> -c <chain>
   mech update-metadata -c <chain>
   

4. Restart:

   mech run -c <chain>
   

Documentation

Find the full tutorial (tool development, publishing, sending requests) at stack.olas.network.