ecosystem

installing the tova agent

The TOVA agent is the autonomous client that lets your agent source compute, manage credits, and route inference across the network without manual intervention. This guide walks through every step needed to get a working agent on the network.

1. requirements

macOS 12+, Linux (glibc 2.31+), or Windows with WSL2
an Ethereum wallet (MetaMask, Rabby, Frame, or any wallet that exposes a private key or keystore)
ETH on mainnet in that wallet for gas — 0.01 ETH is enough to get started
$TOVA token held in the same wallet — this is what authorizes the agent on the network
curl, bash, and git available on PATH

info

Without $TOVA in the connected wallet the agent will install and start, but the routing layer will refuse to serve inference. Acquire $TOVA before running your first request.

2. run the installer

The installer detects your platform, drops the tova binary into ~/.tova/bin, and adds it to your PATH.

curl -fsSL https://tova.run/install.sh | bash

Open a new shell, then verify the binary is installed:

tova --version
# tova 0.4.2 (build 2026.05.a)

3. connect your wallet

The agent needs signing access to the wallet that holds your $TOVA so it can authorize requests and auto-refill credits. Run:

tova wallet connect

You will be prompted to either:

paste a private key (stored encrypted in ~/.tova/keystore behind your OS keychain), or
point the agent at an existing keystore JSON file, or
scan a WalletConnect QR code from a mobile wallet

Confirm the wallet is recognized and is holding $TOVA:

tova wallet status
# address:   0xA1b2...9F3c
# eth:       0.0184
# $tova:     1,250.00
# authorized: yes

note

The keystore is encrypted with a passphrase you set during wallet connect. Lose the passphrase and the agent cannot sign — back it up the same way you would back up any wallet.

4. fund your credits

Credits are the unit your agent spends on inference. They are minted against the $TOVA in your wallet. Do an initial top-up so the agent has something to spend on its first request:

tova credits topup --amount 25
# burning 25 $TOVA -> 25,000 credits
# tx: 0x7c1e...d3a4
# confirmed in block 21_984_120

5. configure auto-refill

Auto-refill is what keeps an autonomous agent running. When your credit balance drops below the threshold, the agent signs a refill transaction from your wallet without prompting you.

tova config set refill.enabled true
tova config set refill.threshold 1000     # refill when credits < 1,000
tova config set refill.amount 25          # burn 25 $TOVA per refill
tova config set refill.max_per_day 200    # safety cap

The full config lives at ~/.tova/config.toml and can be edited directly:

[wallet]
address = "0xA1b2...9F3c"
chain   = "mainnet"

[refill]
enabled      = true
threshold    = 1000
amount       = 25
max_per_day  = 200

[routing]
default_model = "auto"        # let tova pick the cheapest healthy provider
fallback      = ["openai/gpt-5", "anthropic/claude-4"]
timeout_ms    = 30000

6. start the agent daemon

The agent runs as a long-lived background process. Start it in the foreground first to confirm it boots:

tova daemon start --foreground

You should see:

[tova] connected to router  rpc.tova.run
[tova] wallet authorized    0xA1b2...9F3c
[tova] credits available    25,000
[tova] refill watcher       armed (threshold 1,000)
[tova] listening            http://127.0.0.1:7842

Once that looks healthy, stop it and run it as a service:

tova daemon install   # registers a launchd / systemd unit
tova daemon start     # runs in background, restarts on crash

7. point your agent at tova

The local daemon exposes an OpenAI-compatible endpoint on http://127.0.0.1:7842/v1. Most agent frameworks will accept this as a drop-in:

# OpenAI SDK (python)
from openai import OpenAI
client = OpenAI(
    base_url="http://127.0.0.1:7842/v1",
    api_key="tova-local",   # auth is handled by the daemon, key is a placeholder
)

resp = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "ping"}],
)
print(resp.choices[0].message.content)

verify end-to-end

tova ping
# router:   ok (38ms)
# wallet:   ok
# credits:  24,997 (-3 this request)
# refill:   armed

8. monitoring

tova logs -f — tail the daemon log
tova credits history — every spend and refill, on-chain tx hashes included
tova wallet status — current ETH, $TOVA, and authorization state
tova doctor — runs every health check and prints a remediation hint for anything failing

troubleshooting

"wallet not authorized"

The connected wallet is not holding $TOVA, or the balance dropped below the network minimum. Top up $TOVA and run tova wallet refresh.

"refill failed: insufficient eth for gas"

The wallet has $TOVA but no ETH to pay gas on the refill transaction. Send a small amount of ETH to the wallet address shown in tova wallet status.

"router unreachable"

The daemon cannot reach rpc.tova.run. Check your network, then run tova doctor --network to diagnose. The daemon will keep retrying with exponential backoff and resume automatically.

info

Once steps 1–6 are done, the agent is fully autonomous. It will hold credits, refill from $TOVA when it runs low, route to the cheapest healthy provider, and keep running across reboots — no human in the loop required.

← previous

the tova token