micromech 0.1.3

Lightweight OLAS mech runtime

micromech

[!CAUTION] micromech is open-source software provided as is, without warranty of any kind. Use it at your own risk. The developers are not responsible for any loss of funds, tokens, rewards, or damages arising from the use of this software. By using micromech you accept full responsibility for the security of your wallet and private keys.

A lightweight mech for the OLAS network. micromech runs an autonomous AI agent (called a "mech") that listens for on-chain requests, solves them using pluggable tools, and delivers results back on-chain.

No prior experience with OLAS or blockchain development is needed to get started.

What You Need

• A computer that can stay on (or a cheap cloud server). 2 GB RAM minimum.
• Docker Desktop — a free app that runs micromech in an isolated container.
  • Download for Windows
  • Download for Mac
  • Download for Linux
• An internet connection.

After installing Docker Desktop, open it once and make sure it's running (you'll see a whale icon in your system tray or menu bar).

Install & Run

Mac / Linux

Open Terminal and run from the directory where you want micromech installed (your home directory is a good default):

cd ~ && bash <(curl -sSL https://raw.githubusercontent.com/dvilelaf/micromech/main/scripts/quickstart.sh)

This creates a micromech/ folder in the current directory. If you want to install in a system directory like /opt, use sudo with a pipe instead (process substitution doesn't work with sudo):

cd /opt && curl -sSL https://raw.githubusercontent.com/dvilelaf/micromech/main/scripts/quickstart.sh | sudo bash

Windows

Open a WSL terminal (search "WSL" in the Start menu) and run:

cd ~ && bash <(curl -sSL https://raw.githubusercontent.com/dvilelaf/micromech/main/scripts/quickstart.sh)

If WSL is not installed, open PowerShell as Administrator and run wsl --install, then restart your computer. Docker Desktop must be set to use the WSL 2 backend (this is the default).

Access the Dashboard

Open http://localhost:8090 in your browser. The setup wizard will guide you through creating your wallet, choosing a chain, and deploying your mech.

Running on a remote server? Forward the dashboard to your local machine with an SSH tunnel:

ssh -L 8090:localhost:8090 user@your-server

Then open http://localhost:8090 in your local browser.

[!WARNING] Back up your wallet as soon as the setup wizard is complete. Copy data/wallet.json to a safe location (e.g. an external drive or cloud storage) before adding any funds. If you lose this file and have no backup, access to your funds is permanently lost and cannot be recovered.

Day-to-Day Commands

Run these from inside the micromech/ folder. If you have just installed, the shortcuts make things easier — otherwise use the docker compose equivalents.

What you want to do	just shortcut	docker compose equivalent
Start micromech	just up	docker compose up -d
Stop micromech	just down	docker compose down
View live logs	just logs	docker compose logs -f
Update to latest image	just update	docker compose pull && docker compose up -d
Update Justfile + docker-compose.yml	just update-config	(no equivalent)
Check container status	just status	docker compose ps
Re-run setup wizard	just init	(no equivalent)
Run health check	just doctor	(no equivalent)

micromech restarts automatically if your computer reboots.

Repair updater files

If just update reports an impossible version or seems stuck on old updater files, run the repair script from the micromech folder. This preserves data/ and secrets.env, regenerates updater files, checks updater permissions, and updates the container.

cd ~/micromech
tmp=$(mktemp)
status=0
if curl -fsSL -o "$tmp" https://raw.githubusercontent.com/dvilelaf/micromech/main/scripts/repair-updater.sh && bash -n "$tmp"; then
  bash "$tmp" || status=$?
else
  status=$?
fi
rm -f "$tmp"
[ "$status" -eq 0 ]

Remote Control via Telegram (Optional)

Control your mech from your phone. Configure it from the dashboard, then use these commands:

Command	What it does
/status	Mech status, deliveries, and rewards per chain
/wallet	Wallet addresses and balances per chain
/queue	Pending, executing, and failed requests
/manage	Stake, unstake, or restake per chain
/claim	Claim staking rewards
/checkpoint	Call staking checkpoint manually
/contracts	Staking contract info per chain
/last_rewards	Accrued staking rewards for the current epoch
/withdraw	Withdraw pending mech payments
/addresses	Export all wallet addresses as a CSV file
/settings	Toggle features and edit values (e.g. auto-checkpoint)
/logs	Download last 24h logs as a zip file
/info	Version and runtime information
/update	Pull latest image and restart
/restart	Restart the mech runtime
/help	List all available commands

Your Files

After the quickstart, your micromech/ folder contains:

File	What it is	Notes
secrets.env	Passwords, API keys, Telegram token, custom RPC endpoints	Never share. This is the main file you'll edit.
docker-compose.yml	Docker configuration	Leave it alone unless you need to change ports.
data/	All persistent data (wallet, database, config, AI models)	Back this up regularly.
data/config.yaml	Mech settings: chains, mech addresses, staking contracts	You can edit it, but the web dashboard is easier.
data/wallet.json	Your encrypted wallet (private key + recovery phrase)	Never share. Back this up.
data/micromech.db	SQLite database of all requests — pending, delivered, failed	Grows over time. Safe to delete if disk space is tight (history only, no funds).
data/backup/	Pre-update snapshots of wallet.json and config.yaml	Created automatically before each update. Safe to delete old ones manually.
data/.hf_cache/	Cached AI model files (downloaded on first use)	Large (~300 MB). Safe to delete — re-downloads automatically.
updater.sh	Auto-update script (called by the container on startup)	Don't touch.
Justfile	Command shortcuts (requires just)	Optional convenience, safe to ignore.

Backup reminder: Copy the entire data/ folder somewhere safe. If you lose data/wallet.json, you lose access to your wallet.

Staking Rewards

Staking rewards are only paid if your mech receives enough requests and delivers them successfully within each staking epoch. Being online is not sufficient on its own — if no requests reach your mech, the staking contract will consider it inactive and withhold rewards for that epoch.

If you are not receiving enough requests, coordinate with traders or other agents to route demand to your mech address.

For Developers

git clone https://github.com/dvilelaf/micromech
cd micromech && uv sync --all-extras
just check       # lint + types
just security    # gitleaks + bandit
just test        # pytest

License

Apache-2.0