Agent Terminal guide: existing vaults (legacy)

An AgentVault is a small on-chain wallet that you own. Your AI agent has its own separate key. That key 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 22+, a terminal, the Pelagus wallet that owns the vault, and an AI agent that can run an MCP server (Claude Code, Claude Desktop, Codex or similar).

#Step 1: find your vault

1. Open hartiilabs.com/agent.
2. Connect the wallet that owns the vault. Until you do, the page says "Connect your owner wallet to read existing vaults."
3. Look under Legacy vault recovery. Each vault shows its QUAI balance, Per-trade cap, Remaining today and Recent activity.

If the page says "No existing vaults found for this wallet.", this wallet does not own a vault. Connect the wallet that created it. The page offers no way to create one.

#Step 2: connect the agent

The vault MCP server starts read-only. To let your existing agent act on your vault, select the legacy profile. A Claude Code .mcp.json entry:

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

Use the real path of your agent key file and your vault address. Then ask the agent "Check my Hartii vault status". It should call hartii_status and report balance, holdings and caps.

Without the HARTII_MCP_PROFILE line the server stays read-only. It does not read the key at all. An older config that set only the key and the vault used to enable every tool. It now starts read-only until you add the line.

#Step 3: replace the agent key (only if you must)

Do this if an agent key is lost or may be compromised.

1. On the agent's machine, run:

   bashCopy

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

   It makes a fresh key on that machine, saves it to ~/.hartii-agent/agent.key (owner-only permissions where the system supports them) and prints only the new address and the file path. It refuses to overwrite an existing key file unless you pass --force. The key is never shown, and Hartii never sees it. The address must be in Cyprus-1, so the command searches until it finds one. That can take a moment.

2. On your vault's card, click Change agent and enter the new address.

3. Point HARTII_AGENT_KEY_FILE at the new file.

keygen --force replaces an existing key file for good, and it can lock you out if the old key is still in use. keygen only serves existing vaults. There is no new-vault 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:

• 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. QUAI spending is capped per transaction and over a rolling 24 hours. The contract checks all of it. See Contracts and Security.

#Common mistakes

#Next

• Personal trader: try it in Paper (beta)
• Agent Terminal overview
• MCP setup and Agent API
• Want a local, wallet-based agent first? CLI guide 3