Coorporate Hermes operations guide.

Start here

Coorporate Hermes is a company-oriented distribution of Hermes. The base assistant still works as a local CLI, TUI, dashboard, tool runner, skill runtime, MCP client, gateway, and cron scheduler. The corporate edition adds tenant governance, role and team identity, approval workflows, guarded migration, and audit logs.

Installation

The source repository contains the installer, dashboard, CLI, skills, plugins, cron runtime, and governance code. Linux, macOS, and WSL2 are the normal desktop/server targets. Android Termux has a dedicated installer path. Native Windows shells are not supported for the full stack; use WSL2 and clone inside the Linux filesystem rather than under /mnt/c.

Quick install

git clone https://github.com/and270/coorporate-hermes.git
cd coorporate-hermes
./setup-coorporate.sh

The installer checks for uv, provisions Python 3.11 when needed, creates the project virtual environment, installs dependencies, bootstraps Node.js/npm for the dashboard frontend when needed, creates .env from the template, links the coorporate command, and syncs bundled skills into the Coorporate Hermes home directory.

After installation

source ~/.zshrc        # or: source ~/.bashrc
coorporate setup      # configure model provider and keys
coorporate status     # inspect configuration
coorporate doctor     # diagnose missing dependencies

First run and model setup

Do not start with every feature enabled. First prove that a normal conversation works with the chosen model and provider. Then add dashboard, skills, messaging gateway, cron jobs, and governance.

Choose a provider

coorporate model

Supported provider types include direct API keys, OAuth-style providers, OpenAI-compatible endpoints, local/self-hosted models, gateway providers, and multi-provider fallback. Keep secrets in the managed `.env` flow rather than in memories, prompts, runbooks, or shared files.

Verify the assistant

coorporate
coorporate --tui
coorporate --continue

A healthy first run should show the selected model/provider, load tools and skills without errors, answer a simple prompt, and resume the session with `--continue`.

Recommended first prompts

• Ask it to summarize the current repository and identify the main entrypoint.
• Ask it to list available tools and explain which ones are enabled.
• Ask it to inspect a harmless folder that the user is allowed to access.

Dashboard and onboarding panel

The dashboard is the preferred place for non-developers to configure and operate Coorporate Hermes. It exposes configuration, API keys, sessions, logs, analytics, cron jobs, skills, governance, knowledge approvals, and onboarding guidance. Authorized admins and managers can also ask the agent to make configuration changes; the agent uses the same role-aware governance context and must route sensitive changes through audited dashboard, CLI, or tool-backed paths.

coorporate dashboard
coorporate dashboard --port 9119
coorporate dashboard --no-open
coorporate dashboard --status
coorporate dashboard --stop

Dashboard access and network exposure

The dashboard is an administrative surface, not the normal end-user interface. It can read and write configuration, API keys, provider settings, sessions, logs, cron jobs, folder policies, plugins, and knowledge approvals. Treat it like an admin console.

Protection model

Enable protected mode

dashboard:
  auth:
    enabled: true
    token_env: COORPORATE_DASHBOARD_TOKEN
    local_token_roles: [admin]
    read_roles: [auditor, manager, admin]
    manage_roles: [manager, admin]
    admin_roles: [admin]

export COORPORATE_DASHBOARD_TOKEN="$(openssl rand -base64 32)"
coorporate dashboard --host 0.0.0.0 --no-open

This token mode is a bootstrap and system-admin mode. It is for the person operating the server or a small platform-admin group; it is not how normal team members should be identified.

Gateway required before channel access

Channel-based dashboard access only works after a messaging gateway is configured and running. For company rollouts, start with Slack, Discord, Mattermost, or Matrix. Telegram, WhatsApp, and other channels are supported when a company intentionally uses them, but they are not the first recommended corporate path.

coorporate setup gateway
coorporate gateway run     # foreground test
# or: coorporate gateway install && coorporate gateway start

How team leaders log in

The default built-in path uses the identity already authenticated by Slack, Discord, Mattermost, Matrix, Telegram, WhatsApp, or another configured gateway. No company SSO is required for this flow, and admins do not need to copy /whoami output into YAML for the normal path.

1. The admin enables dashboard.auth.channel_tokens, sets dashboard_url, and keeps approval required.
2. The team leader sends /dashboard in a private/direct chat with the bot.
3. Coorporate Hermes creates a pending request in Dashboard Access with the authenticated actor key, display name, platform, and request time.
4. A system admin opens Dashboard Access, reviews the request, fills name, roles, and teams, then approves or denies it.
5. On approval, Coorporate Hermes writes the user record under governance.users.
6. The team leader sends /dashboard again. Coorporate Hermes verifies approval, checks that access is not revoked, sends a one-time token, and accepts it in the dashboard login form.
7. The admin can later revoke or restore dashboard access from the same page.

dashboard:
  auth:
    enabled: true
    read_roles: [auditor, manager, admin]
    manage_roles: [manager, admin]
    admin_roles: [admin]
    channel_tokens:
      enabled: true
      ttl_minutes: 10
      dashboard_url: "https://hermes.company.example"
      require_dm: true
      approval_required: true

governance:
  users:
    "discord:99887766":
      name: Ana Marketing Lead
      roles: [manager]
      teams: [marketing]
  team_file_roots:
    marketing:
      path: "/srv/company/marketing"
	      manager_roles: [manager]
	      managers: ["discord:99887766"]

There is one dashboard application, not a separate system dashboard and team dashboard. The logged-in identity decides which controls are available. A system admin sees global configuration, secrets, plugin settings, delegated roots, and all file policies. A team leader with a delegated team root sees only the file policies under that team root and the approval surfaces allowed by their roles. Operators normally use Coorporate Hermes through CLI or gateways such as Slack, Telegram, Discord, WhatsApp, or other configured channels; they do not need dashboard access unless the company grants it.

Optional company SSO or proxy

Coorporate Hermes does not provide SSO, VPN, zero-trust networking, or an identity-aware reverse proxy. If your company already operates one of those access layers, Coorporate Hermes can sit behind it and consume a trusted user header. The external proxy must authenticate the human, strip spoofed identity headers from client requests, and inject only its own authenticated identity header.

dashboard:
  auth:
    enabled: true
    trusted_user_header: X-Auth-Request-User
    trusted_name_header: X-Auth-Request-Name
    trusted_platform: sso

Channel tokens are issued only after approval by default, short-lived, consumed on first use, stored hashed under <HERMES_HOME>/dashboard/channel_login_tokens.json, and accepted by the normal dashboard login form. Keep require_dm: true unless the platform can guarantee private replies.

Role gates

Safe access patterns

• Run it locally on the server and access it through SSH port forwarding: ssh -L 9119:127.0.0.1:9119 user@server.
• If your company already has a private VPN or zero-trust tunnel, expose the dashboard only through that protected path with SSO/MFA in front of it.
• If your company already has a reverse proxy, use TLS and trusted identity headers only after stripping spoofed client headers.
• Do not bind the dashboard to 0.0.0.0 on a shared LAN or public server without dashboard.auth.

Dashboard access requests, approvals, denials, revocations, restores, channel-token issuance, mutating dashboard API calls, login/logout, and denied role checks are written to the audit log when observability audit logging is enabled.

Gateway setup guides

The gateway is how most employees should use Coorporate Hermes. It connects the same agent runtime to company communication platforms, applies allowlists and role mapping, isolates sessions by user where needed, and can issue dashboard access requests through /dashboard. For company rollouts, configure one corporate channel first, prove it with a small admin group, then invite broader teams.

Recommended order

coorporate setup gateway
coorporate gateway run       # foreground test
coorporate gateway status
coorporate logs gateway

Slack setup

Slack is the first recommended corporate path because Socket Mode works without exposing a webhook endpoint to the internet. Coorporate Hermes connects outward to Slack and receives events over a WebSocket.

1. Generate the manifest after installation: coorporate slack manifest --write. This writes the Slack app manifest under the Coorporate Hermes home directory and includes the required scopes, Socket Mode, events, and slash commands.
2. Open api.slack.com/apps, choose Create New App, then create it from the generated app manifest. If you build from scratch, add the scopes and event subscriptions manually.
3. Under OAuth & Permissions, verify bot scopes: chat:write, app_mentions:read, channels:history, channels:read, groups:history, im:history, im:read, im:write, users:read, files:read, and files:write. Add groups:read if private-channel discovery is required.
4. Under Socket Mode, enable Socket Mode and create an app-level token with connections:write. Save it as SLACK_APP_TOKEN; it starts with xapp-.
5. Under Event Subscriptions, subscribe to message.im, message.channels, message.groups, and app_mention. Missing channel events are the most common reason Slack works in DMs but not in channels.
6. Under App Home, enable the Messages tab and allow messages from the tab, or direct messages to the bot can be blocked by Slack.
7. Install the app to the workspace and copy the Bot User OAuth Token as SLACK_BOT_TOKEN; it starts with xoxb-. Reinstall after changing scopes, events, or slash commands.
8. Copy the Slack member IDs for the people allowed to use the bot. Use member IDs such as U01ABC2DEF3, not display names.

# Interactive path
coorporate setup gateway

# Manual path in <HERMES_HOME>/.env
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
SLACK_ALLOWED_USERS=U01ABC2DEF3,U09TEAMLEAD
SLACK_HOME_CHANNEL=C01234567890

After the gateway is running, invite the bot to each channel with /invite @Coorporate Hermes. In channels, start with an @mention; in DMs, users can message the bot directly. Keep SLACK_ALLOWED_USERS narrow until governance roles are reviewed.

Discord setup

Discord uses a bot application. The important details are privileged gateway intents, an invite URL with the correct scopes, and allowlisting by user IDs or role IDs.

1. Open the Discord Developer Portal, create a new application, and name it for your company deployment.
2. Open Bot, create or reset the bot token, and copy it immediately. Store it only in the Coorporate Hermes secrets file.
3. Still under Bot, enable Message Content Intent so the bot can read messages, and enable Server Members Intent if you want username or role resolution.
4. Create an invite URL through the Installation or OAuth2 flow with scopes bot and applications.commands. Give the bot at least View Channels, Send Messages, Read Message History, Attach Files, and Send Messages in Threads.
5. Invite the bot to the server. It may show offline until coorporate gateway run or the installed service starts.
6. Enable Developer Mode in Discord settings, then right-click users, roles, and channels to copy IDs for allowlists, role allowlists, home channels, or channel restrictions.

# Interactive path
coorporate setup gateway

# Manual path in <HERMES_HOME>/.env
DISCORD_BOT_TOKEN=...
DISCORD_ALLOWED_USERS=284102345871466496,198765432109876543
# or authorize by role:
DISCORD_ALLOWED_ROLES=123456789012345678
DISCORD_HOME_CHANNEL=234567890123456789

# Optional behavior controls
DISCORD_REQUIRE_MENTION=true
DISCORD_FREE_RESPONSE_CHANNELS=234567890123456789
DISCORD_IGNORED_CHANNELS=345678901234567890
DISCORD_AUTO_THREAD=true

By default, Discord DMs get direct replies, server channels require an @mention, and shared channels keep separate session history per user. Use free-response channels only for rooms intentionally dedicated to the bot.

Mattermost setup

Mattermost is the recommended path for companies that want self-hosted chat and direct administrative control over the workspace.

1. In Mattermost, enable bot accounts if your server has them disabled.
2. Create a bot account from Integrations or the System Console, give it a clear name, and copy the bot token.
3. Copy the Mattermost server URL, the allowed user IDs, and the home channel ID for cron or proactive messages.
4. Run coorporate setup gateway, choose Mattermost, and enter those values.

MATTERMOST_URL=https://mattermost.company.example
MATTERMOST_TOKEN=...
MATTERMOST_ALLOWED_USERS=26characteruserid,anotheruserid
MATTERMOST_HOME_CHANNEL=channelid
MATTERMOST_REPLY_MODE=off

Mattermost user IDs are not usernames. Copy the actual user ID from the profile or admin interface. Keep the bot account limited to the teams and channels where Coorporate Hermes is approved.

Matrix setup

Matrix is useful for self-hosted or federated environments. Use a dedicated bot user on the homeserver when possible.

1. Create a Matrix bot user, or dedicate an existing service account.
2. Copy the homeserver URL, such as https://matrix.company.example.
3. Generate an access token from the client settings or login API, or use password login if your deployment permits it.
4. Copy allowed user IDs in full Matrix format, such as @ana:company.example, and the home room ID if proactive delivery is needed.
5. If you enable end-to-end encryption, install and test the encryption dependencies before inviting normal users.

MATRIX_HOMESERVER=https://matrix.company.example
MATRIX_ACCESS_TOKEN=...
MATRIX_USER_ID=@coorporate-hermes:company.example
MATRIX_ALLOWED_USERS=@ana:company.example,@bruno:company.example
MATRIX_HOME_ROOM=!roomid:company.example
MATRIX_ENCRYPTION=false

Run, install, and test the gateway

# Foreground test while configuring
coorporate gateway run

# Background service after the platform replies correctly
coorporate gateway install
coorporate gateway start
coorporate gateway status
coorporate logs gateway

• Send a direct message from an allowed user and confirm the bot replies.
• Test one approved shared channel with an @mention and confirm session behavior.
• Send /dashboard in a private/direct chat and confirm the request appears in the dashboard Admin Access page.
• Restart the service and confirm the bot comes back online without re-entering credentials.

Architecture model

Coorporate Hermes separates user experience from corporate control. The assistant can feel like Hermes for the operator while the platform enforces identity, scope, approvals, logs, and policy around it.

Configuration model

Coorporate Hermes keeps normal settings in config.yaml and secrets in .env. Production deployments should make each configuration path explicit: use the dashboard for guided administration, use the agent for authorized self-configuration requests, and use YAML or CLI edits for reviewed server operations and infrastructure-as-code.

Configuration paths

Core files

Baseline corporate configuration

The YAML below is not a separate file to create. It is the underlying shape of <HERMES_HOME>/config.yaml, where HERMES_HOME defaults to ~/.coorporate-hermes. In normal admin use, set these values from the dashboard or ask an authorized admin agent session to make the change; use YAML directly only for server deployments, code review, backups, or infrastructure-as-code workflows.

governance:
  enabled: true
  tenant_id: acme-corp
  role_hierarchy: [viewer, operator, manager, admin]
  default_file_policy: deny

knowledge:
  enabled: true
  corporate:
    approver_roles: [admin]
  team:
    approver_roles: [manager, admin]

observability:
  enabled: true
  audit_log_enabled: true
  redact_sensitive_values: true
  retention_days: 180

Identity, roles, and teams

Corporate governance starts with actor identity. Gateway users are identified as platform:user_id, such as slack:U123456, discord:99887766, telegram:987654321, or whatsapp:+15551234567. CLI and dashboard deployments can use local identities or deployment-specific mappings.

Where this is configured

The example below shows what the dashboard writes behind the scenes. It belongs in <HERMES_HOME>/config.yaml, not in the repository, not in a memory file, and not in a prompt.

governance:
  enabled: true
  tenant_id: acme-corp
  role_hierarchy: [viewer, operator, manager, admin]
  users:
    "slack:U123456":
      name: Finance Manager
      roles: [manager]
      teams: [finance]
    "slack:U222222":
      name: Operations Analyst
      roles: [operator]
      teams: [ops]

How to add a real channel user

1. Confirm a gateway is configured and running. The dashboard Admin Access page shows configured platforms and runtime status.
2. Ask the user to send /dashboard in a private/direct chat if they need dashboard access.
3. Open dashboard Dashboard Access and review the pending request.
4. Assign name, roles, and teams on that request, then approve or deny it.
5. Ask the user to run /whoami only when you need to verify or troubleshoot the resulting mapping.
6. Ask the user to run /dashboard again after approval to receive the one-time login token.

The channel provider authenticates who sent the message. Coorporate Hermes authorizes what that identity can do through the approved Dashboard Access request and the backing governance.users record. Those controls should stay separate.

Memory and skill governance

The largest behavioral difference from upstream Hermes is knowledge hierarchy. Coorporate Hermes keeps user memory and user skills, but adds corporate and team layers above them. Shared layers are approval-first and audit-recorded.

Precedence

Corporate and team knowledge is injected before user memory and user skills. If there is a conflict, the approved corporate/team layer wins. This prevents a user preference or imported skill from weakening organization-wide guardrails.

Approval behavior

knowledge:
  enabled: true
  corporate:
    approver_roles: [admin]
  team:
    approver_roles: [manager, admin]

User-level memory can still behave like classic Hermes. Corporate and team writes become pending proposals. Administrators review them in the dashboard Knowledge panel, approve or deny, and the result is written to the audit trail. Approval roles can be configured from the dashboard, through reviewed YAML, or by asking an authorized agent session to update the configuration and show the resulting change.

Role-aware self-configuration skill

Upstream Hermes includes a hermes-agent skill that teaches the assistant how Hermes config, tools, skills, gateway, cron, and development workflows fit together. Coorporate Hermes keeps that skill, but adds a dynamic governance overlay so the instructions change according to the current actor.

When the skill is loaded, Coorporate Hermes renders a live block from governance, dashboard.auth, knowledge, delegated team roots, and cron authorization config. The block includes the actor key, roles, teams, tenant, dashboard read/manage/admin capability, shared-knowledge approver roles, delegated File Access roots, default file policy, and cron default authorizer roles.

This is the supported "ask the agent to configure itself" path. A user can describe the desired setup, such as adding a team, changing a cron approval role, or enabling a narrow toolset. The agent must verify the actor's role, choose the safest backed configuration route, ask for confirmation when the change is sensitive, and refuse requests that require a higher role.

Shared knowledge remains approval-first

The skill tells the agent not to edit corporate or team memory/skill files directly. Corporate and team updates should be staged with an approval note:

memory(
  action="add",
  scope="team",
  team="finance",
  target="memory",
  content="Finance closes use the approved monthly close checklist.",
  approval_note="Requested by finance manager for team-wide reuse.",
)

skill_manage(
  action="create",
  scope="corporate",
  name="incident-communications",
  content="---\nname: incident-communications\ndescription: Incident update workflow.\n---\n...",
  approval_note="Creates a tenant-wide incident communication runbook.",
)

Migration from upstream Hermes

Coorporate Hermes can import the export archive produced by upstream Hermes, including tar and zip formats, without treating it as a trusted full restore. This is important because personal Hermes exports can contain local habits, stale skills, secrets, experimental MCPs, and filesystem assumptions that are unsafe in a company environment.

coorporate import ~/Downloads/hermes-export.tar.gz --from-hermes-export

What guarded migration does

• Preserves existing corporate governance, approval, terminal, and observability settings.
• Stages imported memories in a migration review folder instead of promoting them.
• Stages imported skills for human review before activation.
• Copies `.env`, `auth.json`, and MCP tokens only into review locations, not active secrets.
• Imports MCP server definitions disabled and redacts secret-like values.
• Writes `report.json` describing imported, staged, and skipped entries.
• Blocks archive path traversal, tar symlinks, and special files.

What guarded migration does not do

• It does not overwrite corporate governance, approval, terminal, or observability settings.
• It does not promote imported memories or skills into corporate/team layers automatically.
• It does not activate imported skills or MCP servers automatically.
• It does not import old secrets into active `.env`.
• It does not restore old sessions as active corporate history.

Post-migration review

1. Open the migration folder printed by the command.
2. Read `report.json` and inspect every skipped or staged item.
3. Review each `SKILL.md` before allowing it into user, team, or corporate scope.
4. Promote department runbooks through the team approval workflow.
5. Promote company policies through the corporate approval workflow.
6. Re-enter secrets through the dashboard Keys page or managed `.env` commands.
7. Enable MCP servers only after reviewing command, URL, tool filters, and required env vars.

File authorization by team and user

File operations are one of the highest-risk parts of an enterprise agent. Coorporate Hermes checks folder policy before reads, searches, writes, patches, deletes, cron jobs, and dashboard-triggered actions. A prompt cannot grant itself a path, and production deployments should start with governance.default_file_policy: deny.

Before creating policies

1. Configure and start the messaging gateway first. Prefer Slack, Discord, Mattermost, or Matrix for company rollouts.
2. Ask users who need dashboard or delegated file administration to run /dashboard in a private/direct chat with the bot.
3. Open dashboard Dashboard Access and approve each request with the right roles and teams.
4. The approved mapping is saved under governance.users and can be used by File Access policies.
5. Open dashboard File Access to add the folder policies.

System admin workflow

1. Log in as a system admin. In token mode this is the local admin token. In SSO or trusted-proxy mode, the mapped user must satisfy dashboard.auth.admin_roles.
2. Open File Access, or ask the agent from an authorized admin session to prepare the same narrow policy and show the planned diff.
3. Set Default file policy to deny.
4. Add shared folders only when the whole tenant should access them, using Read roles and Write roles.
5. Add department folders with Read teams, Write teams, Read users, or Write users.
6. Add Delegated team roots, such as /srv/company/marketing, when a team leader should manage one bounded folder without becoming a system admin.
7. Save, test as a real mapped user, and review governance.file_access audit events for denied attempts.

Team leader workflow

1. The team leader sends /dashboard in a private channel. If already approved, the bot returns a one-time token for the dashboard login form.
2. File Access shows only delegated roots for teams they manage.
3. The team leader clicks Add policy and sets a Server path below the delegated root, or asks the agent to create that policy from the same authorized identity.
4. They use Read teams / Write teams for their managed team or Read users / Write users for named users assigned to that team.
5. They leave Recursive directory policy on for folders and turn it off for one exact file.
6. They cannot change the global default, edit another team's root, grant role-wide access, or reference users outside the managed team unless they also have system-admin dashboard access.

Marketing example

This example is the backing YAML that the dashboard writes to <HERMES_HOME>/config.yaml. The system admin creates users, team roots, and baseline policies. After that, Ana can maintain policies under the marketing root from the dashboard.

dashboard:
  auth:
    enabled: true
    trusted_user_header: X-Auth-Request-User
    trusted_platform: sso
    read_roles: [auditor, manager, admin]
    manage_roles: [manager, admin]
    admin_roles: [admin]

governance:
  enabled: true
  default_file_policy: deny
  users:
    "sso:ana@company.com":
      name: Ana Marketing Lead
      roles: [manager]
      teams: [marketing]
    "sso:bruno@company.com":
      name: Bruno Marketing Analyst
      roles: [operator]
      teams: [marketing]
    "sso:carla@company.com":
      name: Carla Marketing Viewer
      roles: [viewer]
      teams: [marketing]
  team_file_roots:
    marketing:
      path: "/srv/company/marketing"
      manager_roles: [manager]
      managers: ["sso:ana@company.com"]
  folder_policies:
    - path: "/srv/company/shared"
      read_roles: [viewer]
      write_roles: [admin]
    - path: "/srv/company/marketing"
      read_teams: [marketing]
      write_users: ["sso:ana@company.com"]
    - path: "/srv/company/marketing/campaigns"
      read_teams: [marketing]
      write_teams: [marketing]
    - path: "/srv/company/marketing/brand-guidelines.pdf"
      recursive: false
      read_teams: [marketing]
      write_users: ["sso:ana@company.com"]
    - path: "/srv/company/marketing/private-budget.xlsx"
      recursive: false
      read_users: ["sso:ana@company.com"]
      write_users: ["sso:ana@company.com"]

How decisions are made

1. Coorporate Hermes resolves the actor from the channel, CLI, cron job, or dashboard session.
2. It reads the user's roles and teams from governance.users.
3. It resolves the requested path and uses the most-specific matching folder policy.
4. deny_users and deny_teams override broader grants.
5. Reads and searches require read_users, read_teams, or read_roles.
6. Writes, patches, and deletes require write_users, write_teams, or write_roles.

What those fields mean

If no policy matches and default_file_policy is deny, access is denied and audited. File-access denials should be treated as useful evidence, not just errors: they show where a user, prompt, tool, or automation tried to cross a boundary.

Recommended folder model

Tools, skills, MCPs, and gateways

Coorporate Hermes inherits the broad Hermes capability model: toolsets, skills, plugins, MCP servers, messaging gateways, browser tools, code execution, web extraction, image and audio features, and provider routing. The corporate layer adds policy around what is available to whom.

Toolsets

Toolsets group capabilities such as file, terminal, web, browser, code execution, messaging, model operations, and domain integrations. Administrators should enable only the capabilities needed for a role or team. Avoid giving terminal, browser, and unrestricted file access to a broad user group by default.

Configure tools, skills, MCPs, and gateway settings through the dashboard Config pages, the CLI commands below, reviewed YAML, or an authorized agent-assisted request. The agent path is for convenience, not privilege escalation: operators cannot enable their own terminal, file, browser, MCP, or gateway capabilities unless policy already allows it.

Skills

Skills package instructions, references, scripts, and workflows. User skills are personal. Team skills should capture departmental runbooks. Corporate skills should capture global operating procedures and require approval before activation.

MCP servers

MCP servers can expose powerful external systems. Imported MCP definitions are disabled by default during migration. Review the command, endpoint, environment variables, tool names, and data access before enabling.

coorporate tools
coorporate skills
coorporate mcp

Channels, networking, and multi-user control

The messaging gateway is the intended network-facing interface for users. Discord, Slack, WhatsApp, Telegram, Feishu, webhooks, and API-server access should be configured as controlled channels, each with its own identity and authorization rules. The dashboard remains an admin interface.

Inbound request controls

Session isolation for many users

Coorporate Hermes must not treat every message in a shared channel as one shared brain by default. The gateway uses platform user IDs and session keys so different users can be isolated even inside the same visible channel.

governance:
  gateway:
    group_sessions_per_user: true
    thread_sessions_per_user: false

• With group_sessions_per_user: true, Alice and Bob in the same group/channel get separate session history unless an explicit shared thread/topic mode is enabled.
• Gateway context includes the actor platform, user ID, user name, tenant, and governance roles where available.
• The active-session busy path re-checks authorization before accepting additional messages, so an unauthorized user cannot inject into someone else's running session.
• Shared thread or topic modes should be explicit because they intentionally create multi-user context.

Recommended deployment pattern

Run the gateway on a server with outbound access to platform APIs. Expose only the adapters that require inbound webhooks, and put them behind TLS, platform signature verification, secrets, allowlists, and rate limits. Keep the dashboard loopback-only, or enable dashboard.auth and place it behind a separate admin SSO/VPN/TLS path.

# Admin access: local or tunneled only
coorporate dashboard --host 127.0.0.1 --port 9119

# User access: configured channels
coorporate gateway install
coorporate gateway status

Cron jobs and authorization checkpoints

Cron jobs let the agent run prompts on a schedule. In a company, scheduled work can touch governed folders, send messages externally, or produce outputs that require review. Coorporate Hermes can pause jobs before each due run until an authorized person approves.

Create from the dashboard or agent

Use the Cron dashboard for explicit review, or ask the agent from an authorized session to create the job and show the schedule, owner, workdir, delivery target, and authorization rule before saving. Use YAML or CLI automation only for reviewed deployment workflows.

1. Open the Cron page.
2. Create a job with a prompt, schedule, delivery target, owner, and team scope.
3. Enable the authorization checkpoint.
4. Enter approver roles such as `manager, admin`, approver users such as `slack:U123`, or both.
5. Save the job and verify its next run time.

Tool API shape

cronjob(
  action="create",
  name="Legal weekly review",
  prompt="Review the legal folder and prepare a weekly risk summary.",
  schedule="0 10 * * MON",
  workdir="/srv/company/legal",
  authorization={"required": True, "roles": ["manager"]},
)

Approval states

cronjob(action="authorize", job_id="abc123")
cronjob(action="deny", job_id="abc123", reason="Close process is not complete")

Recurring jobs reset approval status after each successful run, so the next due run requires fresh approval.

Observability and audit trail

Observability has two layers: runtime logs for operational debugging and corporate audit events for governance decisions. Do not rely on model/session analytics alone for enterprise evidence.

Runtime logs

<HERMES_HOME>/logs/agent.log
<HERMES_HOME>/logs/errors.log
<HERMES_HOME>/logs/gateway.log
<HERMES_HOME>/logs/mcp-stderr.log

coorporate logs
coorporate logs errors
coorporate logs gateway --component gateway

Audit log

The audit trail is append-only JSONL by default at `/logs/audit.jsonl`. It records file-access denials, knowledge approval requests, approvals and denials, cron authorization requests, cron approvals and denials, dashboard access requests, approvals, denials, revocations, restores, channel-token issuance and denials, dashboard login/logout, dashboard role denials, mutating dashboard API calls, and other governance events.

coorporate logs audit

Configuration

Configure observability through the dashboard, reviewed YAML, or an authorized agent request. In production, keep audit logging and redaction enabled unless an admin intentionally changes them through a reviewed process.

observability:
  enabled: true
  audit_log_enabled: true
  audit_log_path: ""
  redact_sensitive_values: true
  siem_webhook_url: ""
  siem_timeout_seconds: 2
  retention_days: 180

Set `siem_webhook_url` only after the collector is private, authenticated at the network layer, and approved for governance metadata. Keys containing token, secret, password, credential, cookie, private key, or API key are redacted when redaction is enabled.

Governance and security mapping

Coorporate Hermes is designed to support controls commonly expected in enterprise AI deployments. This does not automatically certify an installation, but it gives implementers concrete hooks for policy, review, and evidence.

Controls to verify before production

• Default file policy is deny, with explicit folder allowlists.
• Corporate and team knowledge changes require human approval.
• Scheduler jobs that touch sensitive folders require authorization checkpoints.
• Audit logging is enabled and retained long enough for review.
• Secrets are stored in managed `.env`, never in memories, skills, or docs.
• MCP servers and imported skills are disabled until reviewed.

Operational routines

A reliable deployment needs recurring administration. The dashboard should make these checks visible, but the operating model should be explicit.

Day 0 checklist

• Install from the GitHub repository and verify `coorporate status` and `coorporate doctor`.
• Configure at least one model provider and prove a normal chat works.
• Open the dashboard and complete onboarding.
• Define tenant, users, teams, role hierarchy, and folder policies.
• Enable audit logging and decide retention.
• Import old Hermes exports only through guarded migration.

Weekly review

• Review audit events for denials, approvals, imports, and cron decisions.
• Review pending Knowledge approvals and reject stale proposals.
• Review cron jobs that are paused, denied, or failing.
• Review team membership and role changes from HR or IT.
• Check provider usage, cost, and failure patterns.

Backup and update

coorporate backup
coorporate update
coorporate checkpoints

Backups created by Coorporate Hermes are distinct from guarded upstream Hermes imports. Use full restore only for backups created by this distribution and guarded migration for upstream Hermes export archives.

Troubleshooting

Publishing, source, and license

Coorporate Hermes is maintained by Ampliia as a corporate edition derived from the MIT-licensed Hermes project. The original Nous Research project remains credited in the repository and license. The public source is hosted at GitHub.