# Hermes Hub by Bewize.ai LLM Documentation This file contains the external-safe Hermes Hub documentation intended for LLM retrieval systems. It is specifically for Hermes Hub by Bewize.ai. Bewize has other projects and product areas; this reference covers only Hermes Hub. Context7 library: https://context7.com/llmstxt/bewize_ai_llms_txt --- # External REST API Contract Hermes Hub exposes an HTTP API for managing hosted Hermes Agent tenants, their runs, shared storage, skills, cron jobs, credentials, and operator policy. Use the Hub URL provided by your operator. Management endpoints require `Authorization: Bearer `. Successful responses are JSON unless an endpoint streams events or downloads file bytes. Errors use problem-style JSON with fields such as `code`, `message`, and `status`. ## Endpoint Groups - Health and metadata: `GET /v1/healthz`, `GET /v1/readyz`, `GET /v1/version`. - Tenants: `GET/POST /v1/tenants`, `GET/PATCH/DELETE /v1/tenants/{tenantId}`, `GET/PUT /v1/tenants/{tenantId}/access`. - Tenant lifecycle: `GET /v1/tenants/{tenantId}/agent`, `POST /v1/tenants/{tenantId}/agent/start`, `POST /v1/tenants/{tenantId}/agent/stop`, `POST /v1/tenants/{tenantId}/agent/restart`, `GET /v1/tenants/{tenantId}/agent-card`. - Runs: `POST /v1/tenants/{tenantId}/runs`, `GET /v1/tenants/{tenantId}/runs/{runId}`, `GET /v1/tenants/{tenantId}/runs/{runId}/events`, `POST /v1/tenants/{tenantId}/runs/{runId}/stop`, `POST /v1/tenants/{tenantId}/runs/{runId}/approval`. - Files: `GET /v1/tenants/{tenantId}/files`, `GET /v1/tenants/{tenantId}/files/content`, `GET /v1/tenants/{tenantId}/files/download`. - Tenant environment keys: `GET /v1/tenants/{tenantId}/env`, `PUT/DELETE /v1/tenants/{tenantId}/env/{name}`. - Skills: `GET /v1/tenants/{tenantId}/skills`, `GET /v1/tenants/{tenantId}/skills/{category}/{skill}/files`, `GET /v1/tenants/{tenantId}/skill-files/{skillPath}`, `PUT /v1/tenants/{tenantId}/skills/{skillName}/state`. - Agent cron: `GET/POST /v1/tenants/{tenantId}/agent-cron`, `GET/PATCH/DELETE /v1/tenants/{tenantId}/agent-cron/{jobId}`, `POST /v1/tenants/{tenantId}/agent-cron/{jobId}/pause`, `POST /v1/tenants/{tenantId}/agent-cron/{jobId}/resume`, `POST /v1/tenants/{tenantId}/agent-cron/{jobId}/run`. - Share groups: `GET/POST /v1/share-groups`, `GET/PATCH/DELETE /v1/share-groups/{groupId}`, `PUT/DELETE /v1/share-groups/{groupId}/members/{tenantId}`, `GET /v1/tenants/{tenantId}/shares`. - Share files: `/v1/tenants/{tenantId}/shares/{groupId}/list`, `read`, `stat`, `grep`, `find`, `write`, `mkdir`, `move`, and `remove`. - A2A: `POST /a2a/{tenantId}`, `GET /a2a/{tenantId}/.well-known/agent.json`, `GET /a2a/{tenantId}/.well-known/agent-card.json`, peer management under `/v1/tenants/{tenantId}/a2a-peers`. - Credentials and secrets: tenant A2A/API credentials, managed secret metadata, write-only material replacement, refresh, and rotation endpoints. - Flavors, releases, and evals: release management, flavor catalog and versions, flavor eval suites and runs. - Policy and configuration: agent policy, known features, specialization, tenant policy overrides, and tenant-impacting config. - Metrics and business keys: run metrics, schedule metrics, aggregate usage, and business key lifecycle. - Webhooks: WhatsApp and Telegram webhook ingestion. Paths under `/v1/tenant-runtime/{tenantId}/...` are reserved for tenant runtime callbacks and hub-managed runtime proxying. External clients should not call them directly unless implementing a compatible tenant runtime. --- # MCP Contract Hermes Hub exposes MCP Streamable HTTP at `/mcp`. HTTP requests require `Authorization: Bearer `. Tools return MCP text content containing JSON from the underlying Hub operation. An empty successful response is returned as `{"ok":true}`. ## Tenant Tools - `list_tenants`: input `{}`. - `get_tenant`: input `{"tenant_id":"tenant_123"}`. - `create_tenant`: input follows the REST create tenant request. - `update_tenant`: input includes `tenant_id` plus update fields. - `delete_tenant`: input `{"tenant_id":"tenant_123"}`. - `set_tenant_access`: input includes `tenant_id`, access status, optional message, and optional reason. ## Skill Tools - `list_tenant_skills`: `{"tenant_id":"tenant_123"}`. - `list_tenant_skill_files`: `{"tenant_id":"tenant_123","category":"content","skill":"writer"}`. - `get_tenant_skill_file`: `{"tenant_id":"tenant_123","path":"content/writer/SKILL.md"}`. ## Share Filesystem Tools - `list_shares`: `{"tenant_id":"tenant_123"}`. - `list_share_files`: `tenant_id`, `group_id`, `path`. - `read_share_file`: `tenant_id`, `group_id`, `path`, optional `offset`, optional `limit`. - `stat_share_path`: `tenant_id`, `group_id`, `path`. - `grep_share`: `tenant_id`, `group_id`, `path`, `pattern`, optional `max`, optional `ignore_case`. - `find_share_files`: `tenant_id`, `group_id`, `path`, optional `name`, optional `max`. - `write_share_file`: `tenant_id`, `group_id`, `path`, `content`, optional `mode` (`overwrite` or `append`). Requires write access. - `make_share_dir`: `tenant_id`, `group_id`, `path`. Requires write access. - `move_share_path`: `tenant_id`, `group_id`, `from`, `to`. Requires write access. - `remove_share_path`: `tenant_id`, `group_id`, `path`, optional `recursive`. Requires write access. ## Cron Tools - `list_tenant_crons`, `get_tenant_cron`, `create_tenant_cron`, `update_tenant_cron`, `delete_tenant_cron`, `pause_tenant_cron`, `resume_tenant_cron`, `run_tenant_cron`. Cron tools use `tenant_id`; job-specific tools also use `job_id`. Create and update bodies follow the active Hermes Agent cron schema. ## Settings Tools - `get_tenant_impact_config`, `patch_tenant_impact_config`. - `get_agent_policy`, `put_agent_policy`. - `get_agent_specialization`, `put_agent_specialization`. ## Context Sync Tool - `sync_context`: copies tenant context to a destination reachable by the MCP server. Input: `tenant_id`, `destination`, `dry_run`, `delete`. Use read-only tools before mutating tools. Do not include bearer tokens in prompts, logs, or persisted transcripts. --- # Hermes Agent Tenant Environment `~` is private to the tenant. Use `~/workspace` for durable user-visible artifacts and `~/company` for shared company/team material when enabled. `~/workspace` is where agents should save final reports, images, documents, datasets, and other artifacts that users need to access. `~/company` is the tenant-facing company or team storage view: - Org-wide access shows the company storage tree. - Scoped team access shows only teams or departments the tenant can access. Important environment variables: - `HERMES_TENANT_ID`: current tenant id. - `HOME`: tenant home directory. - `HERMES_HOME`: tenant runtime root. Use `HOME`, `~/workspace`, and `~/company` for normal file work. - `HERMES_WORKSPACE`: backing path for `~/workspace`, when storage is enabled. - `HERMES_COMPANY_ROOT`: backing path for `~/company`, when company/team storage is available. - `HERMES_TEAMS`: scoped team grants such as `teams/division1:write`. - `HERMES_SHARED_STORAGE_ACCESS`: org-wide company storage access. - `HERMES_SHARED_ROOT_WRITABLE`: whether root-level company storage writes are allowed. - `HERMES_BROWSER_ENABLED`: browser support flag. - `CAMOFOX_URL`: local browser automation endpoint when browser support is enabled. - `HERMES_PUBLIC_HOST`: tenant public host when configured. - `HERMES_AGENT_VERSION`: active agent version label. - `HERMES_HUB_CODEX_PROXY_BASE_URL`, `HERMES_HUB_CODEX_MODEL`, `HERMES_HUB_VISION_PROXY_BASE_URL`, `HERMES_HUB_VISION_MODEL`: Hub-managed model proxy settings. - `HERMES_HUB_TENANT_RUNTIME_KEY`: tenant runtime credential. Never print or log it. Agents should use the `codex` launcher on `PATH` for LLM calls. Browser support is available only when `HERMES_BROWSER_ENABLED=true` and `CAMOFOX_URL` is set. Rules: - Use `~/workspace` for final user artifacts. - Use `~/company` for shared company/team material only. - Do not put secrets in shared storage. - Do not print raw environment variables. - Do not expose tenant runtime credentials. - Prefer tenant-visible paths in final answers.