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
| Chain | Native | OLAS Token | USDC Token | Nevermined |
|---|---|---|---|---|
| Gnosis | ✅ | ✅ | ❌ | ✅ |
| Base | ✅ | ✅ | ✅ | ✅ |
| Polygon | ✅ | ✅ | ✅ | ✅ |
| Optimism | ✅ | ✅ | ✅ | ✅ |
Requirements
- Python
>=3.10, <3.12 - Docker Engine + Docker Compose
Commands
| Command | Description |
|---|---|
mech setup -c <chain> |
Full first-time setup: workspace, agent build, mech deployment, env config, key setup |
mech add-tool <author> <name> |
Scaffold a new mech tool |
mech prepare-metadata --name <name> -c <chain> |
Recompute package fingerprints, push packages and metadata to IPFS, and write METADATA_HASH and TOOLS_TO_PACKAGE_HASH to .env |
mech prepare-metadata --name <name> -c <chain> --offchain-url <url> |
Same as above, also sets the offchain URL in metadata and .env |
mech prepare-metadata --name <name> -c <chain> --operator-name <op> --operator-domain <host> |
Same as above, also records who operates the mech (--operator-contact is optional) |
mech prepare-metadata --name <name> -c <chain> --benchmark-url <url> --benchmark <tool> <metric> <window> |
Same as above, also links each tool to its live score (--benchmark is repeatable) |
mech prepare-metadata --name <name> -c <chain> --terms-url <url> |
Same as above, also publishes the operator's terms link in the metadata and on off-chain responses |
mech prepare-metadata --name <name> -c <chain> --erc8004-agent-id <id> |
Same as above, with the ERC-8004 agent id set by hand instead of resolved from the marketplace |
mech update-metadata -c <chain> |
Update the metadata hash on-chain via Safe transaction |
mech run -c <chain> |
Run the mech AI agent via Docker |
mech stop -c <chain> |
Stop a running mech AI agent |
Developing a new tool
New service (no existing mech)
-
Set up the workspace and deploy the mech on-chain:
mech setup -c <chain>
-
Scaffold a tool:
mech add-tool <author> <tool_name> -d "Tool description"
-
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
-
If your tool requires API keys or other secrets, add them to
~/.operate-mech/.env. -
(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_URLin~/.operate-mech/.env.<chain>and runprepare-metadatawithout the flag. -
Generate and publish metadata (to IPFS), then update the on-chain registry.
--nameis the human-readable mech name and is required:mech prepare-metadata --name <name> -c <chain> mech update-metadata -c <chain>
-
Run:
mech run -c <chain>
Existing service (mech already running)
-
Stop the service:
mech stop -c <chain>
-
Scaffold, implement, and set any required API keys (same as steps 2–4 above).
-
Generate and publish metadata (to IPFS), then update:
mech prepare-metadata --name <name> -c <chain> mech update-metadata -c <chain>
-
Restart:
mech run -c <chain>
Documentation
Find the full tutorial (tool development, publishing, sending requests) at stack.olas.network.
Metadata
Release files for mech-server 0.8.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mech_server-0.8.6.tar.gz | 1.2 MB | Without provenance | Details for mech_server-0.8.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mech_server-0.8.6-py3-none-any.whl | Python 3 | none | any | Details for mech_server-0.8.6-py3-none-any.whl |
Total release size: 2.7 MB
Release files / mech_server-0.8.6.tar.gz
| Download URL | mech_server-0.8.6.tar.gz |
|---|---|
| Size | 1.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
08d22e318c4397f1c4c3952087369fdd8fd7ac484a09cb2da86c4297115b11cb
|
|
BLAKE2b-256 checksum How to use checksums |
9b6fa4f2319b82120e8c50f1063d36ce85b05a928648c26270be9c02f5765747
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / mech_server-0.8.6-py3-none-any.whl
| Download URL | mech_server-0.8.6-py3-none-any.whl |
|---|---|
| Size | 1.5 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
21ffadb51b3cbc6ed8336ba94e9b6742ad93eff91197800610788b9181c609be
|
|
BLAKE2b-256 checksum How to use checksums |
ada3cf2beb15345bfe03755b83b3a758ab5e22d7ddacbe1800409b6ed5f71a08
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for mech-server 0.8.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.