> For the complete documentation index, see [llms.txt](https://docs.rujira.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rujira.network/developers/deploy-your-own-defi-ai-agent.md). # Deploy Your Own DeFi AI Agent Practical guide for Rujira community members who want to run their own always-on AI agent to do DeFi. This guide uses Hermes Agent, an open-source, self-hosted autonomous AI agent built by Nous Research, as the agent runtime. Hermes runs on a VPS, connects to an external LLM provider, and exposes a Telegram bot so you can control it from your phone. Hermes Agent is designed as a persistent personal assistant that runs continuously on a user's own infrastructure (such as a $5 VPS, local machine, or serverless environment) rather than being a session-based chatbot. The setup below keeps costs low by running only the agent on the VPS and sending model calls to Codex/OpenAI, Claude/Anthropic, OpenCode, or another provider. ### What You Will Build ``` Telegram app on your phone | | messages v Telegram bot | | Hermes gateway v VPS running Hermes Agent | +-- LLM provider: Codex, Claude, OpenCode, etc. +-- Skills: Rujira, Vultisig, coding workflows +-- Optional wallet tooling through Vultisig ``` The VPS is the always-on machine. The LLM provider is the brain. Telegram is the remote control. Skills are instruction packs that teach the agent how to do specific work. ### Before You Start You need: * A basic comfort level with SSH and terminal commands. * A VPS with Ubuntu 24.04 LTS. * One LLM provider account. * A Telegram account. * Optional: a Vultisig wallet if you want the agent to help with wallet operations. Security rule: start with read-only tasks. Do not give an agent meaningful funds, production credentials, or broad server access on day one. ### 1. Rent A VPS Hermes Agent itself does not need a large server when it uses external model APIs. Recommended starting size: ``` 2 vCPU 4 GB RAM 40 GB disk or more Ubuntu 24.04 LTS ``` You can usually run smaller, but 2 vCPU and 4 GB RAM leaves more room for browser tools, logs, skills, and package installs. #### Recommended Providers | Provider | Best For | Suggested Plan Shape | | ------------- | --------------------------- | -------------------------------- | | Hetzner Cloud | Low-cost EU hosting | 2 vCPU / 4 GB RAM Ubuntu server | | DigitalOcean | Beginner-friendly dashboard | 2 vCPU / 4 GB RAM Ubuntu Droplet | Choose Hetzner if you mostly care about price. Choose DigitalOcean if you want a simpler dashboard and more beginner-friendly docs. ### 2. Prepare The Server Connect into the server as root with SSH: ```bash ssh root@YOUR_SERVER_IP ``` Create a normal user for Hermes: ```bash adduser hermes usermod -aG sudo hermes ``` If you use SSH keys, copy your root SSH keys to the new user: ```bash rsync --archive --chown=hermes:hermes ~/.ssh /home/hermes ``` Switch to the Hermes user: ```bash su - hermes ``` Install the small set of packages Hermes needs before its installer runs: ```bash sudo apt update sudo apt install -y git curl xz-utils ca-certificates ufw ``` Enable a basic firewall: ```bash sudo ufw allow OpenSSH sudo ufw enable ``` Do not open random inbound ports yet. The Telegram polling setup works with outbound HTTPS only, so you do not need to expose a web server. ### 3. Install Hermes Agent Install Hermes Agent with the official installer: ```bash curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash ``` Reload your shell: ```bash source ~/.bashrc ``` Check that the command is available: ```bash hermes doctor ``` If `hermes` is not found, add the user-local binary path: ```bash echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc source ~/.bashrc ``` Hermes stores its main files here: | Path | Purpose | | ----------------------- | -------------------------- | | `~/.hermes/config.yaml` | Non-secret config | | `~/.hermes/.env` | API keys and secrets | | `~/.hermes/skills/` | Local skills | | `~/.hermes/sessions/` | Conversation/session state | | `~/.hermes/logs/` | Runtime logs | Run the setup wizard: ```bash hermes setup ``` If you use Nous Portal (a web UI), the shortest setup path is: ```bash hermes setup --portal ``` After setup, start a local test chat: ```bash hermes ``` Ask something harmless: ``` Explain what files are in my current directory. Do not edit anything. ``` Exit with `Ctrl+C` or `/quit`. ### 4. Connect An LLM Provider Hermes needs at least one model provider. The easiest way is the interactive model setup: ```bash hermes model ``` This writes the model choice into Hermes config and stores secrets in `~/.hermes/.env` or Hermes auth storage. #### Option A: Codex / OpenAI Use this if you already use ChatGPT/Codex or OpenAI API. Hermes supports two useful OpenAI paths: | Path | Hermes Provider | When To Use | | -------------- | --------------- | ---------------------------------------------------------------- | | Codex OAuth | `openai-codex` | You want Hermes to authenticate with ChatGPT/Codex device login. | | OpenAI API key | `openai-api` | You want direct API billing through an OpenAI API key. | Interactive setup: ```bash hermes model ``` Choose OpenAI Codex if you want the device-code login flow. For direct OpenAI API usage, edit: ```bash nano ~/.hermes/.env ``` Add: ```bash OPENAI_API_KEY=replace_with_your_key ``` Then choose OpenAI API in: ```bash hermes model ``` Optional: if you also use the Codex CLI and want Hermes to call Codex as a tool through MCP, configure the Codex MCP preset: ```bash hermes mcp add codex --preset codex ``` This is separate from using OpenAI/Codex as the model provider. #### Option B: Claude / Anthropic Use this if you already use Anthropic API or Claude Code. Edit the Hermes environment file: ```bash nano ~/.hermes/.env ``` Add: ```bash ANTHROPIC_API_KEY=replace_with_your_key ``` Then run: ```bash hermes model ``` Choose Anthropic. Hermes also supports Anthropic OAuth through `hermes model`, but current Hermes docs note that this path requires Claude Max plus extra usage credits. If that is confusing, use `ANTHROPIC_API_KEY`. #### Option C: OpenCode Go Use this if you want a cost-efficient coding model provider. OpenCode has two relevant provider paths in Hermes: | OpenCode Product | Hermes Provider | Env Var | | ---------------- | --------------- | ---------------------- | | OpenCode Go | `opencode-go` | `OPENCODE_GO_API_KEY` | | OpenCode Zen | `opencode-zen` | `OPENCODE_ZEN_API_KEY` | OpenCode Go is the cheaper monthly option in current OpenCode docs. Prices can change, so check the official OpenCode page before relying on the number. Edit: ```bash nano ~/.hermes/.env ``` Add: ```bash OPENCODE_GO_API_KEY=replace_with_your_key ``` Then run: ```bash hermes model ``` Choose OpenCode Go and pick the model offered by the wizard. Use the wizard instead of hardcoding model names, because provider catalogs change. ### 5. Connect Hermes To Telegram Telegram lets you control the agent from anywhere. The simple VPS setup uses polling, so the VPS does not need an inbound public web server. #### Create A Telegram Bot 1. Open Telegram. 2. Message `@BotFather`. 3. Send: ``` /newbot ``` 4. Pick a display name. 5. Pick a username ending in `bot`. 6. Copy the bot token. Treat the bot token like a password. Anyone with the token can control the bot. #### Find Your Telegram User ID Hermes uses numeric Telegram user IDs, not usernames. The Hermes docs suggest using: * `@userinfobot` * `@get_id_bot` Save the numeric ID. #### Configure Telegram In Hermes Run: ```bash hermes gateway setup ``` Choose Telegram and enter: * Bot token from BotFather. * Your numeric Telegram user ID. The wizard writes the config for you. Manual config lives in: ```bash ~/.hermes/.env ``` The important values are: ```bash TELEGRAM_BOT_TOKEN=replace_with_bot_token TELEGRAM_ALLOWED_USERS=123456789 ``` Use comma-separated IDs for multiple allowed users: ```bash TELEGRAM_ALLOWED_USERS=123456789,987654321 ``` Do not use: ```bash GATEWAY_ALLOW_ALL_USERS=true ``` That would let anyone who finds the bot talk to an agent that may have terminal and wallet tools. #### Test Telegram Run the gateway in the foreground: ```bash hermes gateway ``` Open Telegram and message your bot: ``` hello ``` If it replies, the connection works. Stop the foreground gateway with `Ctrl+C`. #### Keep The Gateway Running After Logout Install Hermes gateway as a user service: ```bash hermes gateway install hermes gateway start hermes gateway status ``` Make sure it keeps running after you log out: ```bash sudo loginctl enable-linger $USER ``` View logs: ```bash journalctl --user -u hermes-gateway -f ``` For a VPS, this user-service plus linger setup is usually enough. If you prefer a boot-time system service, Hermes also supports: ```bash sudo hermes gateway install --system sudo hermes gateway start --system sudo hermes gateway status --system ``` Use one gateway service style, not both. #### Useful Telegram Commands Inside Telegram, try: | Command | Purpose | | -------------------- | ---------------------------------------- | | `/help` | Show available commands | | `/new` | Start a fresh conversation | | `/status` | Show current session status | | `/model` | Show or switch model if configured | | `/stop` | Stop a running task | | `/background ` | Run a task in the background | | `/sethome` | Set the current chat as the home channel | For group chats, keep Telegram privacy mode in mind. With privacy mode on, the bot mostly sees commands and direct replies. With privacy mode off, or if the bot is an admin, it can see more group messages. Use group access carefully. ### 6. Add Useful Skills Skills are instruction files. They teach Hermes how to handle a specific kind of work, like Rujira contract interactions, Vultisig wallet actions, or code review. The easiest is to PASTE these instructions into hermes once setup and tell him to save these skills. Hermes skills live under: ``` ~/.hermes/skills/ ``` A typical skill looks like: ``` ~/.hermes/skills/blockchain/rujira/SKILL.md ~/.hermes/skills/wallets/vultisig/SKILL.md ~/.hermes/skills/software/coding-practices/SKILL.md ``` Do not copy third-party skill contents from this guide. Skill files can change. Always fetch or inspect the latest version from the source. #### Rujira Skill Use the latest Rujira skill file from the Rujira UI repository: ``` https://gitlab.com/thorchain/rujira-ui/-/blob/agentic-skills/packages/main/public/SKILL.md?ref_type=heads ``` Suggested local path: ``` ~/.hermes/skills/blockchain/rujira/SKILL.md ``` This skill gives the agent Rujira-specific context: secured assets, contract interaction patterns, FIN, Ghost, staking, bRUNE, deployment lookup, and safe transaction checks. #### Vultisig Skill Use the latest Vultisig skill file: ``` https://vultisig.com/skills/SKILL.md ``` Suggested local path: ``` ~/.hermes/skills/wallets/vultisig/SKILL.md ``` This skill teaches the agent how to reason about Vultisig, MPC wallets, CLI usage, SDK usage, supported chains, and wallet operations. #### Hermes Built-In And Optional Skills Hermes ships with bundled skills and optional skills. Check the official catalogs: ``` https://hermes-agent.nousresearch.com/docs/reference/skills-catalog https://hermes-agent.nousresearch.com/docs/reference/optional-skills-catalog ``` Useful categories for Rujira community agents: | Skill Type | Why It Helps | | ------------------------ | ----------------------------------------------------------------------------- | | Coding workflow skills | Better code review, repo exploration, testing, and refactoring. | | Git/GitHub/GitLab skills | Help with issues, PRs, commits, and release notes. | | Docker/Linux skills | Help maintain the VPS and debug services. | | Security review skills | Help catch risky shell commands, leaked secrets, and unsafe wallet workflows. | | Research skills | Help summarize docs, contracts, and protocol changes. | Keep skills focused. A huge skill that tries to teach everything usually works worse than a small skill for one exact workflow. ### 7. Set Up A Vultisig Wallet For The Agent Use a wallet only after the agent is stable, the Telegram allowlist is working, and you understand what commands it can run. For AI agents, Vultisig is useful because it is an MPC wallet. In simple terms, the private key is split across parties, so the server does not need to hold one normal seed phrase that can drain everything if stolen. #### Wallet Safety Rules * Start with tiny amounts. * Keep a separate human wallet for large balances. You need to first gather experience with the agent. * Use allowlists for Telegram users. * Keep the VPS updated. #### Install Vultisig CLI Follow the latest Vultisig skill and docs. Current quick start: ```bash npm install -g @vultisig/cli ``` Check the command: ```bash vultisig --help ``` Inspect the current create command before using it: ```bash vultisig create fast --help ``` Follow the latest Vultisig skill for the exact command. Prefer interactive prompts if available, so secrets do not land in shell history. #### Choose A Vault Type | Vault Type | Best For | Tradeoff | | ----------- | ------------------------------------------ | --------------------------------------------- | | FastVault | Small agent wallet, bots, quick automation | Faster, more convenient | | SecureVault | Higher-value funds, team custody | More coordination, safer for serious balances | For a first Rujira agent wallet, use FastVault only with limited funds. Move to SecureVault for meaningful treasury or protocol operations. #### First Wallet Tasks Start with read-only checks: ``` What is my THORChain address? Show my RUNE balance. Show my RUJI balance. Explain what transaction you would build, but do not sign it. ``` Only after that should you test a tiny transfer. ### 8. Rujira-Specific First Tasks Once Hermes, Telegram, skills, and optional Vultisig are working, start with safe Rujira tasks: ``` Using the Rujira skill, explain the difference between secured assets and contract-created tokens. ``` ``` Find the current docs for Rujira FIN integration and summarize the swap flow. Do not build a transaction. ``` ``` Given this contract config response, explain which denom should be attached as funds. ``` ``` Draft a transaction plan for staking, but stop before signing. ``` When you start using the agent for real wallet operations, require the agent to show: * Contract address. * Exact execute message. * Exact funds array. * Expected denom. * Amount in base units and display units. * Risk notes. * A clear "ready to sign?" confirmation. ### 9. Maintenance Update the server: ```bash sudo apt update sudo apt upgrade -y ``` Update Hermes: ```bash hermes update ``` Restart the gateway if needed: ```bash hermes gateway stop hermes gateway start ``` Check status: ```bash hermes gateway status ``` Check logs: ```bash journalctl --user -u hermes-gateway -n 100 --no-pager ``` Back up important config: ```bash tar -czf hermes-backup-$(date +%Y%m%d).tar.gz ~/.hermes/config.yaml ~/.hermes/skills ``` Do not blindly back up `~/.hermes/.env` or wallet material to cloud storage. It contains secrets. ### Troubleshooting | Problem | Likely Cause | Fix | | ---------------------------------- | --------------------------------------- | -------------------------------------------------------------- | | `hermes: command not found` | `~/.local/bin` not in PATH | Reload shell or add `export PATH="$HOME/.local/bin:$PATH"` | | Hermes says no model is configured | Provider setup not complete | Run `hermes model` | | Telegram bot does not reply | Gateway not running or user not allowed | Run `hermes gateway status` and check `TELEGRAM_ALLOWED_USERS` | | Telegram works in DM but not group | Privacy mode or group permissions | Configure privacy in BotFather or make bot admin | | Gateway stops after SSH logout | User service not lingering | Run `sudo loginctl enable-linger $USER` | | Agent can answer but not use tools | Tools not configured | Run `hermes tools` | | Agent spends too much | Expensive model/provider | Switch provider/model with `hermes model` | | Wallet actions feel risky | Too much permission too soon | Go back to read-only tasks and require manual signing | ### Security Checklist Before using the agent for anything important: * `TELEGRAM_ALLOWED_USERS` is set. * `GATEWAY_ALLOW_ALL_USERS` is not set. * The bot token is not in a public repo. * API keys are only in `~/.hermes/.env` or provider auth storage. * The VPS uses SSH keys. * The VPS firewall is enabled. * Wallet funds are limited. * The agent explains transaction details before signing. * You know how to stop the gateway: ```bash hermes gateway stop ``` ### References * Hermes Agent installation: * Hermes Agent quickstart: * Hermes AI providers: * Hermes MCP: * Hermes Telegram setup: * Hermes messaging gateway: * Hermes skills system: * Hermes bundled skills catalog: * Hermes optional skills catalog: * Rujira skill file: * Vultisig skill file: * Vultisig SDK repository: * Hetzner Cloud: * DigitalOcean Droplets: * OpenCode providers: * OpenCode Go: * OpenAI Codex auth: * Anthropic authentication: --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.rujira.network/developers/deploy-your-own-defi-ai-agent.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.