# How to connect Box to Hermes Agent (no API keys)

> Connect Box to Hermes with ClawLink in one click — 284 tools your AI agent can call from chat via hosted OAuth. No API keys, no manual setup.

Web version: https://claw-link.dev/hermes/box

Most guides for giving Hermes Agent Box access start with registering your own OAuth app or pasting API keys into env files, then leave the token refresh and tool wiring to you. ClawLink gives Hermes a more practical Box setup: pair once in the browser and your always-on Hermes agent can act on Box for you, reading and doing real work on your behalf with no auth, token refresh, or tool wiring to build yourself.

**Start here — paste this into Hermes to set up ClawLink:**

> Set up ClawLink for Hermes and tell me when it's ready.
> 1. Install the plugin: `hermes plugins install ClawLink-HQ/hermes-plugin --enable`
> 2. Start pairing with `hermes clawlink begin`. It prints an approval link, so show me the link and stop, don't wait.
> 3. I'll approve it in my browser, then reply "approved".
> 4. When I say approved, finish setup: `hermes clawlink finish`
> 5. Then run `hermes clawlink test` and tell me whether ClawLink is ready.

## Setup

It takes three steps to connect Hermes to Box.

1. **Install ClawLink** — add the plugin to Hermes Agent once.
2. **Connect Box** — one-click OAuth in the ClawLink dashboard.
3. **Use it from chat** — ask Hermes Agent in plain English.

**Alternative for any agent (no plugin needed):** if the Hermes Agent plugin route isn't available or doesn't work, any AI agent with shell access can use the ClawLink CLI instead:

```bash
npx -y @useclawlink/cli login          # sign in via browser — no API key to paste
npx -y @useclawlink/cli connect box  # connect Box (browser OAuth)
npx -y @useclawlink/cli actions box  # list available actions
npx -y @useclawlink/cli run box <action> --input '<json>'  # execute (add --confirm for writes)
```

### Install by command

The prompt above walks Hermes through this. By hand, it is four commands and a browser approval:

```bash
hermes plugins install ClawLink-HQ/hermes-plugin --enable
hermes clawlink begin    # prints an approval link — open it and approve
hermes clawlink finish   # after approving in the browser
hermes clawlink test
```

Then connect Box in the [ClawLink dashboard](https://claw-link.dev/dashboard) — a one-click OAuth approval, no API keys.

Verify the connection by asking Hermes:

> Search Box for files named like \<name> and show me their paths, owners, and last modified dates with box_get_file_information.

### Using a different agent?

The Hermes plugin is one client of ClawLink's MCP server. Claude Code, Cursor, Codex, or any agent that can run a shell command pairs with the same ClawLink account through the CLI:

```bash
npx -y @useclawlink/cli login
```

`login` opens the same browser approval and stores a credential locally. Once Box is connected in the dashboard, that agent calls the same 284 Box tools over MCP. Full setup for MCP clients and shell agents: [connect apps to any AI agent](https://claw-link.dev/learn/connect-apps-to-any-ai-agent).

## Box MCP for Hermes

Looking for a Box MCP server for Hermes Agent? ClawLink connects Box to Hermes Agent and exposes 284 Box tools your agent can call over [MCP](https://claw-link.dev/learn/what-is-an-mcp-server), with [hosted auth](https://claw-link.dev/learn/oauth-for-ai-agents) and nothing to run or maintain yourself. Using OpenClaw instead? The [OpenClaw Box integration](https://claw-link.dev/openclaw/box) works the same way.

The standard answer for giving Hermes Agent a Box connection is a build-it-yourself recipe from Box's own blog: install the Box CLI, create a CCG app in the Box Developer Console, define a shared workspace, authenticate, and host it, with a 47K-view YouTube video teaching the whole thing. It works, and it is a small infrastructure project. The newer answer is Box's own hosted MCP server at mcp.box.com, which removes the infrastructure but still lives in the MCP-client world. This page is the third option, the one Perplexity already quotes for "a simpler hosted option": ClawLink connects Box with one-click user OAuth, no CCG app, no CLI, no MCP endpoint to configure. You approve Box's authorization screen once and the 284 Box tools below become callable from Hermes chat as your account.

## What the Hermes Agent Box integration can do

284 Box tools are ready for Hermes Agent once the account is connected. The 30 below are the ones people reach for most; your agent can call all 284.

### 30 of 284 Box tools for Hermes

| Tool | What it does |
|---|---|
| **Add allowed collaboration domain** `box_add_allowed_collaboration_domain` | Add an allowed domain for collaboration |
| **Add classification to file** `box_add_classification_to_file` | Add a classification to a file |
| **Add shared link to file** `box_add_shared_link_to_file` | Add a shared link to a file |
| **Add shared link to folder** `box_add_shared_link_to_folder` | Add a shared link to a folder |
| **Add user to group** `box_add_user_to_group` | Add a user to a group |
| **Apply watermark to file** `box_apply_watermark_to_file` | Apply a watermark to a file |
| **Ask question** `box_ask_question` | Ask questions about Box files using Box AI |
| **Authorize user** `box_authorize_user` | Authorize a user by sending them through the [Box](https://box.com) website and request their |
| **Download file** `box_download_file` | Returns the contents of a file in binary format |
| **Download zip archive** `box_download_zip_archive` | Downloads a zip archive containing files and/or folders from Box |
| **Extract metadata freeform** `box_extract_metadata_freeform` | Extract metadata from Box files using AI with freeform prompts |
| **Extract metadata structured** `box_extract_metadata_structured` | Extract structured metadata from files using Box AI |
| **Find app item for shared link** `box_find_app_item_for_shared_link` | Returns the file, folder, web link, or app item represented by a shared link |
| **Find file for shared link** `box_find_file_for_shared_link` | Returns the file represented by a shared link |
| **Find folder for shared link** `box_find_folder_for_shared_link` | Return the folder represented by a shared link |
| **Find metadata template by instance ID** `box_find_metadata_template_by_instance_id` | Finds a metadata template by searching for the ID of an instance of the template |
| **Generate text** `box_generate_text` | Generate text using Box AI based on a prompt and file context |
| **Get AI agent** `box_get_ai_agent` | Retrieves detailed information about a specific AI Agent by its unique identifier |
| **Get AI agent default configuration** `box_get_ai_agent_default_configuration` | Retrieve the default AI agent configuration for a specific mode |
| **Get allowed collaboration domain** `box_get_allowed_collaboration_domain` | Retrieves details of a specific allowed collaboration domain entry within your enterprise |
| **Get box sign request** `box_get_box_sign_request` | Retrieves the details of a specific Box Sign request by its unique ID |
| **Get box sign template** `box_get_box_sign_template` | Retrieves details of a specific Box Sign template by its unique ID |
| **Get collaboration** `box_get_collaboration` | Retrieves details of a single collaboration by its ID |
| **Get collection** `box_get_collection` | Retrieves details of a specific collection by its unique identifier |
| **Get comment** `box_get_comment` | Retrieves the message and metadata for a specific comment, as well as information on the user |
| **Get current user** `box_get_current_user` | Retrieves information about the user who is currently authenticated |
| **Get device pin** `box_get_device_pin` | Retrieves information about an individual device pin in the enterprise |
| **Get events long poll endpoint** `box_get_events_long_poll_endpoint` | Returns a list of real-time servers that can be used for long-polling user events |
| **Get file information** `box_get_file_information` | Retrieves the details about a file |
| **Get file request** `box_get_file_request` | Retrieves detailed information about a file request in Box |

## Example prompts

**Find the file**

> Search Box for files named like \<name> and show me their paths, owners, and last modified dates with box_get_file_information.

**Summarize a folder**

> List the top-level contents of folder \<id> and tell me what is there: file types, sizes, and anything that looks stale from before \<date>.

**Download with approval**

> Show me the files in \<folder> first. I will pick which one, then you download it with box_download_file.

**Ask your content**

> Use box_ask_question against the documents in folder \<id> and answer: what are the key terms in the latest contract, and which parties are named?

## How the Box tools behave

Details that decide whether a Box prompt is a clean read or a permissions-shaped surprise.

- **Ids come from Box, not from links.** `box_find_file_for_shared_link` and `box_find_folder_for_shared_link` map web links to real ids; a link pasted as an id fails like a typo.
- **Find is separate from download.** Metadata reads can succeed where content is blocked by item-level policy, so a failed download is often a policy, not a bug.
- **Writes touch shared space.** Moving, deleting, adding shared links, and editing collaborations affect what your team sees. Confirm before the agent executes them.
- **Metadata and classification are real surfaces.** `box_extract_metadata_structured`, `box_extract_metadata_freeform`, and classification tools read and write the governance layer, which is where enterprise value lives.
- **AI tools exist.** `box_ask_question` and `box_generate_text` operate over Box content with the account's access, which makes them powerful and worth scoping in the prompt.
- **The connection is the account.** Visibility, permissions, and revocations are exactly the authorizing Box account's; if the agent cannot see it, the account cannot either.

## ClawLink vs. building it yourself

The alternative to ClawLink is usually manual OAuth app setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Box working from chat.

| | Manual | ClawLink |
|---|---|---|
| **Connection flow** | Register a Box app, configure redirect URLs, manage consent details, and reconnect users when auth settings drift. | Users connect Box through the hosted browser flow and ClawLink keeps the token lifecycle out of your app code. |
| **Ongoing maintenance** | You own refresh logic, permission debugging, environment config, and every provider-specific edge case for Box. | ClawLink handles the repetitive integration plumbing so your team can focus on the workflow instead of the infrastructure. |
| **Agent usability** | You still need to expose the right Box actions to the runtime in a format your agent can reliably use. | 284 tools for Box are already exposed through ClawLink, so the agent can read and act from chat immediately. |

## ClawLink vs. Composio

Composio also exposes Box to AI agents. It is developer infrastructure: Python and TypeScript SDKs, an MCP server, and a catalog past 1,000 apps, aimed at teams shipping agent products. ClawLink is built for Hermes Agent users instead. You install the plugin once, connect Box in the browser, and the 284 tools above work from chat. There is no SDK, no config file, and no API key handling. Choosing between them? Read the full [Composio alternatives](https://claw-link.dev/hub/composio-alternatives) comparison.

### Hermes paired but still can't use Box
Pairing is a two-step handshake: run `hermes clawlink begin`, approve the link in your browser, then run `hermes clawlink finish`. If you ran finish before approving, or the approval link expired, run `hermes clawlink begin` again to get a fresh link. Confirm the plugin was installed with `--enable`, then verify with `hermes clawlink test`.

### Connection succeeds but no tools appear
Reconnect Box from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

### "Tool schema not loaded yet" error when calling Box tools
Box tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every Box call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.

### Box returns 403 or "permission denied" on one action while others work
Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.

### Box returns 403 "insufficient permissions" on some files
Box's own error surface names this `access_denied_insufficient_permissions`, and the engines' answers give the cause map: item access versus connection access, app access level, and re-authorization after a scope change. In this flow the practical versions are: the connected Box account genuinely lacks access to the item (a folder shared with it that excludes the file, or a workspace it was never invited to), the agent used a placeholder id (a file or folder id from documentation instead of one from a list call), or the OAuth grant predates a scope change and needs a reconnect. Have the agent quote the error, name the item id, and confirm which Box account it is acting as before anything else.

Ask the agent to diagnose it:

```text
Call box_get_current_user and tell me which Box account this connection acts as. Then quote the exact 403 and the item id from the failing call. Do not retry it yet.
```

### Box tools are missing, or one tool name is not found
The engines' answer to this symptom is a JSON `mcp.servers.box-remote-mcp` config block with `BOX_CLIENT_ID` and `BOX_CLIENT_SECRET` environment variables plus admin-console permission checks, all of which assumes a self-hosted or admin-managed MCP server. This flow has none of that. The real causes here are the hosted two: the connection or pairing is incomplete (confirm the plugin installed with `--enable`, both pairing commands ran, and Box shows as connected), or schemas load on demand, so the first Box call in a fresh session can arrive before the catalog and needs one retry. If most tools work and one name fails, that name is wrong rather than missing.

Ask the agent to diagnose it:

```text
List the Box tools you actually have access to. If there are none, say so plainly. If there are, tell me which one downloads a file and use that exact name.
```

### The agent can find a file but cannot download it
Finding a file and downloading its content are different permissions in Box. The find or metadata read can succeed while the content download fails on a shared-link or item-level restriction: a folder shared via link only, a file whose download is blocked, or a shared-link arrangement that grants preview but not download. The second cause is the hosted classic: the agent used the shared-link item id instead of the underlying file id, and `box_find_file_for_shared_link` is the tool that maps between them. Have it resolve the real file id and quote the error before reconnecting, because reconnecting will not change an item-level policy.

Ask the agent to diagnose it:

```text
Tell me which file id you used and where it came from. Call box_find_file_for_shared_link if you have a link, and box_get_file_information on the id you used. Quote the exact download error.
```

### Reconnect after a Box scope change
When Box changes what an app can do, or the account's access changes, existing authorizations can silently stop covering the new surface, and Box's docs answer 403s after scope changes with re-authorization. In this flow that means one thing: reconnect Box from the ClawLink dashboard and approve the consent screen again, then start a fresh chat so the tool catalog reloads. If a reconnect does not change the behavior, the boundary is almost certainly account-level, not connection-level: the connected Box account does not have access to the item, and no amount of reconnecting fixes that.

Ask the agent to diagnose it:

```text
Tell me whether you reconnected after the last Box scope change, and which Box account approved the connection. Quote the exact error that persists. Do not reconnect a second time yet.
```

### OAuth finished in the browser but the account is still missing
Try reconnecting Box and complete the consent flow in the same browser session. Partial OAuth approvals or switching accounts mid-flow can leave the connection incomplete.

### Is there a Hermes Agent Box integration?
Yes. ClawLink is the fastest way to connect Hermes to Box: link your Box account once in the browser and Hermes Agent can call the Box API through 284 ready-made tools — no custom code or token handling.

### How do I connect Box to Hermes with ClawLink?
Install the plugin with `hermes plugins install ClawLink-HQ/hermes-plugin --enable`, then pair once: run `hermes clawlink begin`, approve the link in your browser, and run `hermes clawlink finish`. Connect Box in the dashboard and Hermes can use it from the next message — no config files or API keys to manage.

### How long does it take to connect Box to Hermes Agent?
About two minutes. Sign in, click Connect next to Box in the dashboard, authenticate, and Hermes Agent can use it from the next chat message.

### Why use ClawLink instead of wiring Box up myself?
The alternative to ClawLink is usually manual OAuth app setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Box working from chat.

### How is this different from Box's own hosted MCP server?
Box now ships a hosted MCP server at mcp.box.com with OAuth and no infrastructure to maintain, and it is the right answer for MCP-client setups. The difference is who it serves and how access is granted. Box's MCP is an endpoint you point a client at, typically enabled and governed by an admin for enterprise use. ClawLink is user-side: you approve Box's authorization screen with your own account, the connection shows up in the ClawLink dashboard beside your other accounts, and revoking it there cuts the agent off immediately. If you have an admin-managed Box deployment and MCP clients, Box's own server is the natural fit. If you are one person with a Box account who wants Hermes to read and write files, this is the lower-ceremony route.

### What can the agent do in Box?
The content surface: files and folders including upload, download, copy, move, and shared links, metadata and classifications, comments, collaborations, and the AI-adjacent tools like asking a question of your Box content and generating text. The reads (finding files, listing folders, getting file info) are the safe, high-value surface. The writes to be deliberate about are the shared ones: moving or deleting a file other people use, adding a shared link, and changing collaborations all affect a workspace your team sees.

### Is it safe to connect Box to an agent through ClawLink?
The engines hedge this answer with enterprise governance controls, several of which require Business or Enterprise plans that personal accounts do not have. What actually protects a personal-account setup is smaller and worth stating: the OAuth token is held server-side and never written to a local config file, revoking the connection in the dashboard ends the agent's access at once, and the agent can only reach what your Box account can reach. That last point is the real perimeter: if you connect with a personal account that can see a shared folder, the agent can read it. Scope by what you share, keep the agent read-first, and treat downloads as the action to confirm, since exfiltrated content is the one irreversible outcome.

### What can the agent see, and what can it not?
The connection acts as the Box account you authorized, so visibility is exactly that account's: its own files and folders, anything shared with it, and any collections it belongs to. It cannot reach admin surfaces, enterprise policies, or content governed by classifications the account has no access to, and a service-account or app-access model is a different architecture entirely. If you want the agent to touch a shared workspace, the reliable setup is connecting with an account that can already see it, then testing a read before promising a write.

### Hermes paired but still can't use Box
Pairing is a two-step handshake: run `hermes clawlink begin`, approve the link in your browser, then run `hermes clawlink finish`. If you ran finish before approving, or the approval link expired, run `hermes clawlink begin` again to get a fresh link. Confirm the plugin was installed with `--enable`, then verify with `hermes clawlink test`.

## Related

- [Hermes Neon integration](https://claw-link.dev/hermes/neon) — Serverless Postgres with branching and scale-to-zero
- [Connect ClickHouse](https://claw-link.dev/hermes/clickhouse) — Query analytics databases and inspect schemas
- [Supabase](https://claw-link.dev/hermes/supabase) — Query and manage Postgres databases