# 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`, durable Task callbacks at `POST /a2a/callbacks/{messageId}`, and callback-outbox metrics at `GET /v1/peer-callback-outbox/metrics`. - 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: 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. --- # Hermes Agent Tenant Environment `~` is private to the tenant. `~/workspace` is an always-present private real directory for durable user-visible artifacts. It remains available whether or not company storage is enabled and is never exposed through `~/company`. `~/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. `~/company` is separate from `~/workspace`. If it is absent, the tenant has no company or team storage grant. 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`: always-present backing path for `~/workspace`. - `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. Runtime configuration, prompts, skills, scripts, cron definitions, plugins, credentials, and caches belong under `HERMES_HOME` or another operator-managed runtime location, not under `~/workspace` or `~/company`. --- # Workspace and Company Storage Migration Installing or upgrading Hermes Hub does not automatically move legacy workspace or company data. ```bash hermes-hub workspace migrate --tenant tenant_123 ``` Stop tenant activity and back up Hub configuration, SQLite, tenant homes, legacy workspaces, and company/team data first. Audit symlinks: links resolving outside the workspace are rejected and should be quarantined or replaced deliberately. The migrator stages the copy, verifies regular-file size and SHA-256 plus entry kind, permissions, and symlink target, applies tenant ownership, and atomically installs the private workspace. Directory and symlink inode sizes are ignored because they are filesystem-dependent; file and directory permissions are preserved despite process umask. The legacy source remains for rollback, and a matching repeat returns `already-migrated`. Company data is migrated separately into the dedicated company tree. Never copy the legacy `agents/` workspace tree into company storage. Reconcile only after both data sets are ready, then verify runtime paths, access grants, policy, cron state, Hub health, and database integrity.