Deploy a recurring, self-funding AI agent on Ritual testnet with one command. No API keys.
A sovereign agent is a smart contract that wakes itself on a schedule. On every wake it runs an AI agent inside a secure enclave (TEE), pays for that run from its own on-chain wallet, and keeps going until the money runs out. It lives entirely on-chain.
You need three things. The script installs everything else for you (foundry, uv, and - on Linux/WSL - curl).
- git - to download the code. Most systems already have it; if
git --versionfails, install it (see below). - A wallet on Ritual testnet with a little RITUAL in it. Create one in MetaMask or Rabby, then get free testnet RITUAL from the faucet: https://faucet.ritualfoundation.org
- That wallet's private key (use a throwaway testnet wallet - never a real one). You paste it once, when the script asks.
Installing git (skip if git --version already works):
- Windows: install Git for Windows - it also bundles Git Bash and curl - or run
winget install Git.Git. - macOS:
xcode-select --install(orbrew install git). - Linux / WSL:
sudo apt install git(Debian/Ubuntu), or your distro's package manager.
git clone https://github.com/zunmax/ritual-agent-deployment.git
cd ritual-agent-deploymentcp .env.example .envThere is nothing you must edit - the defaults work. PROMPT is the task your agent runs on every wake, so change it to anything you like.
On Windows (PowerShell):
pwsh run.ps1On Linux / macOS / Git Bash / WSL:
bash run.shEach agent is its own contract at a deterministic address (your wallet + a salt). Run a command with no address to act on the agent named by SALT in .env, or pass an agent address to target a specific one.
| Command | What it does |
|---|---|
bash run.sh |
Deploy + fund + arm. If one is already live, it asks before making another. |
bash run.sh status |
List every agent you have deployed, with state and balance. |
bash run.sh status <address> |
Full detail for one agent. |
bash run.sh topup <address> [wei] |
Add more RITUAL (re-arms it if it was stopped). |
bash run.sh restart <address> |
Re-arm a stopped agent. |
bash run.sh stop <address> |
Stop an agent's schedule. |
Want a second agent? Just run bash run.sh again. It notices your first one is live, asks Deploy another? [y/N], and on yes creates the next (agent-1 -> agent-2, ...).
.env holds no secrets - only your public address and run settings.
| Variable | Purpose |
|---|---|
RPC_URL |
Ritual testnet RPC endpoint. |
CHAIN_ID |
1979 (Ritual testnet). |
DEPOSIT_WEI |
RITUAL locked into the agent's wallet, in wei. 0.015 RITUAL is roughly one wake. |
CLI_TYPE |
Harness type. 6 = ZeroClaw. |
MODEL |
Model id routed through Ritual's gateway (no external key). Default zai-org/GLM-4.7-FP8. |
PROMPT |
The task the agent runs on each wake. |
SALT |
Any unique string - changes the agent address. Use a new one per agent. |
LOCK_BLOCKS |
Optional. Blocks a deposit stays locked. Defaults to 100000. |
KEYSTORE_ACCOUNT |
Written automatically on first run - the name of your keystore. |
WALLET_ADDRESS |
Written automatically on first run - your public address. |
Your private key is never written to .env; it lives encrypted in ~/.foundry/keystores. Still, use a testnet burner wallet - do not import one with real funds.
| Network | Chain ID | RPC | Faucet | SovereignAgentFactory |
|---|---|---|---|---|
| Ritual testnet | 1979 |
https://rpc.ritualfoundation.org |
https://faucet.ritualfoundation.org | 0x9dC4C054e53bCc4Ce0A0Ff09E890A7a8e817f304 |
This tool signs transactions with a key it stores in an encrypted keystore under ~/.foundry/keystores - use a testnet burner wallet, never one with real funds. The deposit you lock funds the agent's scheduled runs and is spent over time - it is not recoverable on a whim. This is testnet software, provided as-is, without warranty, and has not been audited. Use at your own risk.
Released under the MIT License. Built by Zun.