Connect Hermes Agent to your BoxOwl vault

Step 1 — Create an agent token

Open the BoxOwl Android app. Go to Settings → AI Agent Connections → New. Name the token "Hermes Agent on <machine>", pick the scopes you want Hermes to have (a starter set: vault:read, profile:read, agent:query), and tap Generate. The plaintext token is shown exactly once — copy it now.

Token format: bxusr_<8-hex>_<32-char-secret>. See Agent tokens for the full scope vocabulary.

Step 2 — Get the BoxOwl daemon binary

Hermes Agent runs in a Debian-based container, so the daemon binary needs to (a) be inside the container at runtime, and (b) match the container's architecture (typically linux/amd64 — on Apple Silicon, Docker Desktop runs amd64 containers under emulation unless you've explicitly switched to linux/arm64).

Download the matching release from github.com/BoxOwl-Me/daemon/releases:

# Linux amd64 (the default Hermes container arch)
curl -L -o ~/.hermes/boxowl-daemon \
  https://github.com/BoxOwl-Me/daemon/releases/latest/download/boxowl-daemon-linux-amd64
chmod +x ~/.hermes/boxowl-daemon

Putting the binary under ~/.hermes/ means the existing -v ~/.hermes:/opt/data bind-mount in Hermes's docker run command already picks it up at /opt/data/boxowl-daemon inside the container — no extra mount flag needed.

Step 3 — Add a boxowl: block to Hermes config

Edit ~/.hermes/config.yaml (mounted at /opt/data/config.yaml inside the container) and add an mcp_servers.boxowl entry alongside any other MCP servers you've declared:

mcp_servers:
  boxowl:
    command: "/opt/data/boxowl-daemon"
    args: ["mcp"]
    env:
      BOXOWL_AGENT_TOKEN: "bxusr_a1b2c3d4_xT8mPq5KwR9NhL2vYzD3sB6FjUcW1AeXgHnM"
    tools:
      include:
        - boxowl_get_vault_summary
        - boxowl_search
        - boxowl_get_item
        - boxowl_list_items
        - boxowl_workspace_get
        - boxowl_workspace_set

Replace BOXOWL_AGENT_TOKEN with the token you copied in Step 1. The tools.include allowlist is optional but recommended by the Hermes docs — "start with the smallest set possible." A read-mostly starter set is shown above; add write tools (boxowl_put_item, boxowl_delete_item, boxowl_create_login_credential) when you trust Hermes to use them. Write tools are confirmation-gated per the BoxOwl risk-tier matrix regardless.

If you'd rather run the daemon as a long-lived background process on the host (e.g. paired by the desktop already, sharing sync state with other clients), use the HTTP transport instead: replace the command + args + env block with url: "http://host.docker.internal:7741/mcp" + headers: { Authorization: "Bearer bxusr_..." }. Note that boxowl-daemon binds loopback-only by default, so the HTTP path needs --network host (Linux) or the Docker Desktop host.docker.internal alias to reach 127.0.0.1:7741.

Step 4 — Restart Hermes Agent

MCP servers load at gateway startup; config changes need a container restart:

docker restart hermes

Watch the logs to confirm the boxowl server attached:

docker logs -f hermes 2>&1 | grep -i 'mcp\|boxowl'

You should see something like mcp server "boxowl" connected, N tools registered. If Hermes complains the binary isn't executable, double-check the chmod +x from Step 2 + the arch match (file ~/.hermes/boxowl-daemon should report ELF 64-bit LSB executable, x86-64 for the standard amd64 container).

Step 5 — Test a query

Open the Hermes dashboard (http://localhost:9119 if you set HERMES_DASHBOARD=1) or hit the gateway API (localhost:8642) and ask something that requires your vault:

You: What's my shipping address?
Hermes: [calls boxowl_get_item via MCP] Your shipping address on file
        is <your address>. Want me to copy it to a draft message?

Hermes is trained with native function-calling, so it recognizes the BoxOwl MCP tools immediately without prompt-tuning. Confirmation-gated writes (saving credentials, payments) prompt you before they run. The agent-token docs describe the scope vocabulary that controls what Hermes can do.

Manage the connection

In the BoxOwl app go to Settings → AI Agent Connections to see when this token last ran, what it touched, or to revoke it. Revocation is immediate — Hermes's next MCP call after revoke gets a 401 and the boxowl tools stop working until you mint a new token + update ~/.hermes/config.yaml.

Premium users can have unlimited agent tokens; Free users get one. See pricing for the tier breakdown.