Agent Terminal guide: a capped AgentVault

An AgentVault is a small on-chain wallet that you own. Your AI agent gets its own separate key that can only spend from the vault within limits the contract enforces, so the limits hold even if the agent misbehaves. You keep full control: you can change the limits, pause, revoke the agent and withdraw at any time.

You will need: Node.js 20+, a terminal, the Pelagus wallet with a small amount of QUAI, and an AI agent that can run an MCP server (Claude Code, Claude Desktop, Codex or similar).

#Step 1: give the agent its own key

On the machine that will run the agent:

npx -y https://hartiilabs.com/downloads/hartii-agent-mcp.tgz keygen

This creates a fresh key on that machine, saves it to ~/.hartii-agent/agent.key (readable only by you) and prints only the agent's public address and the file path. The key is never shown, and Hartii never sees it. Quai is split into zones and the agent address must be in Cyprus-1, so the command searches until it finds a valid one. That can take a moment.

Copy the printed address. That is the only thing the next step needs.

#Step 2: create the vault

1. Open hartiilabs.com/agent.
2. Click Connect Pelagus and approve.
3. Under Create an agent vault, paste the address into Agent address. The page checks it. If it looks like your own wallet or a contract it warns you; do not tick "I understand" unless you truly intend that.
4. Set Max per trade (QUAI) and Max per day (QUAI). The form starts at 5 and 50. Start lower. The per-trade cap cannot be above the daily cap.
5. Set Fund with (QUAI), the amount deposited into the vault right away. The form starts at 20. Choose a small amount.
6. Click Create vault and approve the transaction in Pelagus.

Your vault then appears under My vaults, showing QUAI balance, per-trade cap, remaining today and recent activity.

#Step 3: connect the agent

Point your agent at the vault with the MCP server. A Claude Code .mcp.json entry:

{
  "mcpServers": {
    "hartii-agent": {
      "command": "npx",
      "args": ["-y", "https://hartiilabs.com/downloads/hartii-agent-mcp.tgz"],
      "env": {
        "HARTII_AGENT_KEY_FILE": "/home/you/.hartii-agent/agent.key",
        "HARTII_VAULT": "<your vault address>"
      }
    }
  }
}

Use the real path printed by keygen and the vault address from your dashboard. Then ask the agent "Check my Hartii vault status". It should call hartii_status and report balance, holdings and caps. More detail: MCP setup.

#Step 4: fund or top up

You can add QUAI later by sending it to the vault's address from your wallet; the vault accepts plain QUAI transfers. Top up in small steps.

#Step 5: manage your vault

On your vault's card in My vaults:

• Change caps asks for a new per-trade cap and a new per-day cap. Lower them whenever you want more safety. Both must be valid amounts and per-trade cannot exceed per-day.
• Pause stops the agent immediately. Unpause lets it continue.
• Change agent swaps in a new agent address, for example after replacing a key.
• Revoke clears the agent and pauses the vault at once. Use it if you suspect the agent or its machine is compromised. It takes effect on-chain regardless of the MCP server.
• Withdraw opens a form with Amount (QUAI) (a Max button fills the whole balance) and a Destination. Use my wallet fills in your connected wallet. Sending to any other address requires ticking that you have double-checked it, and every withdrawal asks you to confirm the amount and destination first.

Only the vault owner (you) can change caps, pause, revoke or withdraw. The agent key cannot.

#What the agent can and cannot do

The agent key can only call the vault's execute, which is limited to an allowlist of Hartii contracts. Token transfer and transferFrom are forbidden, and QUAI spending is capped per transaction and over a rolling 24 hours, all checked by the contract. See Contracts and Security.

#Common mistakes

#Next

• Agent Terminal overview
• MCP setup and Agent API
• Want a local, wallet-based agent first? CLI guide 3