Connect Hermes to AgentKit

Hermes is the self-improving AI agent from Nous Research. Hermes runs where you put it: a laptop, a small VPS, or a GPU cluster. You reach Hermes from the command line, or from a messaging app such as Slack or Telegram, and Hermes also runs work on a cron schedule.

Hermes ships with 60+ built-in tools, and the built-in tools stop at the edge of your machine. A Hermes agent that reads your Gmail, posts to your Slack, or opens a GitHub pull request needs an access token for each app. Every access token belongs to one user.

Scalekit holds the connected account for that user, stores the access token, and refreshes it. Install the Scalekit plugin from the Hermes plugin catalog, paste three Scalekit values once, and Hermes calls your connections with four tools. Access tokens stay in Scalekit: the plugin’s tools don’t return them to the chat.

To manage several users on one Hermes host yourself, use the hermes-delegated-auth skill instead. It’s described later on this page.

• Hermes Agent 0.20.0 or later, installed with the Hermes installer. Run hermes update to upgrade an older install.
• A Scalekit account with AgentKit enabled: sign up at app.scalekit.com
• At least one connection in AgentKit > Connections. Create the connection before you ask Hermes to use the app. See Set up a connection.

The Scalekit plugin is listed in the Hermes plugin catalog. It adds four tools to Hermes and installs no extra Python packages. Quit any open hermes chat before you start.

1. Check the Hermes version

   Section titled “Check the Hermes version”

   hermes --version

   The version must be 0.20.0 or later. If it’s older, run hermes update.

2. Install the plugin from the catalog

   Section titled “Install the plugin from the catalog”

   hermes plugins install scalekit

   Hermes installs the version of the plugin that the catalog lists. To see that entry first, run hermes plugins info scalekit.

3. Paste three API credentials

   Section titled “Paste three API credentials”

   Hermes asks for three values and saves them in ~/.hermes/.env. Copy them from Developers > Settings > API Credentials in the Scalekit dashboard. If Hermes doesn’t ask, the values are already in that file.

   Prompt	What you paste
   SCALEKIT_CLIENT_ID	Your client ID, such as skc_1234 Required
   SCALEKIT_CLIENT_SECRET	Your client secret. This is your Scalekit secret, not a Gmail or Slack token. Required
   SCALEKIT_ENVIRONMENT_URL	Your environment URL, such as https://your-env.scalekit.dev Required

4. Enable the plugin

   Section titled “Enable the plugin”

   When Hermes asks Enable 'scalekit' now?, type Y. If you skipped that prompt, run hermes plugins enable scalekit.

   Start a new hermes chat so the tools load. If a Hermes gateway is already running, restart it with hermes gateway restart.

5. Copy a connection name

   Section titled “Copy a connection name”

   In AgentKit > Connections, copy the name of a connection, such as github-connect. You give Hermes that name. Don’t use the conn_ ID.

Start a new hermes chat and send:

List my Scalekit connections.

Who am I on GitHub? Use the connection github-connect.

Replace github-connect with your own connection name.

• The list shows each connection with its name, type and status, for example github-connect, OAUTH, COMPLETED.
• The first request for an app returns an authorization link. Open the link and finish sign-in on the hosted page, then send the same request again. A scheduled job can’t finish sign-in, so authorize each app in a normal chat first.
• The next request returns your GitHub login and profile URL. The reply doesn’t include the access token.

The plugin creates an identifier (usr_…) on first use and stores it in ~/.hermes/plugin-data/scalekit/identifier. You don’t type it. Updating the plugin keeps the same identifier, so the apps you authorized stay ACTIVE.

hermes plugins update scalekit

Hermes moves the plugin to the version the catalog lists now.

This section covers the hermes-delegated-auth skill. For the plugin, see Install the Scalekit plugin.

The skill runs the following loop when you name an app:

1. The skill looks up the Scalekit connection you already created for GitHub, Gmail, or another app.
2. The skill checks the user’s connected account. ACTIVE means auth is complete and Scalekit holds a token.
3. The skill returns an authorization link when the connected account is not ACTIVE.
4. The skill fetches the tool schema, calls the tool, and returns the result.
5. The skill calls the Scalekit HTTP proxy when the connector has no named tool.

An authorization link is a one-time URL. It opens the Hosted Connect Widget, which shows OAuth consent or an API-key form.

Use this skill instead of the plugin when you want to set the default identifier yourself in ~/.hermes/.env. You also need uv on your PATH.

Using a coding agent?Copy Hermes prompt

1. Install the skill

   Section titled “Install the skill”

   Install hermes-delegated-auth from authstack:

   hermes skills install scalekit-inc/authstack/kits/agentkit/host/hermes-delegated-auth

   Confirm the skill is enabled:

   hermes skills list

   │ hermes-delegated-auth │          │ local  │ local │ enabled │

   Install the Python dependencies:

   cd "${HERMES_HOME:-$HOME/.hermes}/skills/hermes-delegated-auth"
   uv sync

   New chats load /hermes-delegated-auth. Run /reset in a chat that is already open.

   HERMES_HOME changes the skill path. The commands on this page use ~/.hermes.

2. Configure credentials

   Section titled “Configure credentials”

   Put only Scalekit client credentials in ~/.hermes/.env. Scalekit stores and refreshes the provider tokens for GitHub, Gmail, and Slack. Provider tokens never belong in a Hermes file.

   SCALEKIT_CLIENT_ID=skc_your_client_id
   # Keep this secret: anyone who has it can call tools as any ACTIVE identifier.
   SCALEKIT_CLIENT_SECRET=your_client_secret
   SCALEKIT_ENVIRONMENT_URL=https://your-env.scalekit.dev
   SCALEKIT_IDENTIFIER=usr_8f3a2c

   Parameter	Description
   SCALEKIT_CLIENT_ID	Your Scalekit client ID Required
   SCALEKIT_CLIENT_SECRET	Your Scalekit client secret Required
   SCALEKIT_ENVIRONMENT_URL	Your Scalekit environment URL Required
   SCALEKIT_IDENTIFIER	Default user the host acts as Required

   Copy the client ID, client secret, and environment URL from Dashboard > Developers > Settings > API Credentials.

   SCALEKIT_IDENTIFIER is not a dashboard credential. Pick an opaque id that only your system knows, for example usr_8f3a2c. Every tool_exec.py command needs SCALEKIT_IDENTIFIER, including --list-connections.

3. Ask Hermes to act

   Section titled “Ask Hermes to act”

   Start a chat and ask for a real action. Hermes acts as SCALEKIT_IDENTIFIER by default, and Hermes passes --identifier to the skill when you name another user in the prompt.

   • GitHub
   • Gmail
   • Notion
   • Slack (as a user)
   • Google Calendar

   You: Who am I on GitHub?

   Hermes loads the skill and runs these steps:

   1. Hermes looks up the GitHub connection.
   2. Hermes checks that the connected account is ACTIVE, and returns an authorization link when the account is not.
   3. Hermes fetches the tool schema.
   4. Hermes calls the tool and returns your GitHub login.

   Name the skill in the prompt to force the same path:

   /hermes-delegated-auth who am I on GitHub?

Confirm the following for hermes-delegated-auth. For the plugin, see Check it worked.

• The skill is listed (hermes skills list or /skills) as hermes-delegated-auth
• The connected account is ACTIVE after you finish the authorization link
• Hermes returns data from the provider (the GitHub login, or unread mail)

Open the authorization link again and retry the same prompt if the account stays inactive.

Slack issues two kinds of token, and the token decides whose name appears on a message. A bot token posts as your Slack app. A user token posts as the person who authorized the app. Authorizing the Hermes gateway grants a bot token, so the gateway alone cannot post as a person.

The gateway bot is a channel into the agent. The gateway bot is not usr_8f3a2c.

Always-on hosts use both identities. The gateway hears the channel. Scalekit acts as the user.

These commands attach the hermes-delegated-auth skill. With the Scalekit plugin, a scheduled job that reaches an app the user hasn’t authorized returns the authorization link and stops, so authorize each app in a normal chat first.

Attach the skill to a Hermes cron job. Each fire is a fresh session. The skill uses Scalekit client credentials. You do not mint a session token.

hermes cron create "0 9 * * *" "List unread emails for usr_8f3a2c and post a 5-line summary" --skill hermes-delegated-auth

Or in chat:

/cron add "every weekday at 9am" "List unread emails for usr_8f3a2c and post a 5-line summary" --skill hermes-delegated-auth

The connected account must already be ACTIVE. Cron cannot click an authorization link.

Leave the gateway running on a headless host. A new authorization link can then land in Slack or Telegram. Do not put Gmail or Calendar refresh tokens in ~/.hermes/.env.

Pick the path that matches the host.

Scalekit plugin. Install it from the Hermes catalog with hermes plugins install scalekit. Hermes saves three Scalekit values, the plugin creates the identifier, and you name a connection in the chat.

Authstack skill. Install hermes-delegated-auth from authstack. You set SCALEKIT_IDENTIFIER yourself and can name another user per turn.

Virtual MCP in your app. Your application mints a session token before each agent run and passes that token to the agent framework. Claude Managed Agents, Mastra, and CrewAI use this path.

For Virtual MCP in your app, see Create a Virtual MCP server.

• Do not put provider tokens in ~/.hermes/.env. Put only Scalekit credentials there.
• With the Scalekit plugin, let the plugin manage the identifier. Don’t type a usr_… value. The hermes-delegated-auth skill still needs SCALEKIT_IDENTIFIER.
• Do not set SCALEKIT_IDENTIFIER to an email or another guessable value.
• Do not use the bundled Google Workspace skill (~/.hermes/google_token.json) if AgentKit owns the Google user. ~/.hermes/google_token.json is one laptop login, not a per-user identifier.
• Do not run hermes mcp login against Scalekit Virtual MCP (a Scalekit MCP URL plus a session token). Virtual MCP uses a static bearer session token, and a static bearer token is not MCP OAuth.
• Do not treat the Slack bot token as “send as usr_8f3a2c”.
• Do not rely on Hermes to sign in your end users. One gateway belongs to one operator, who holds the Scalekit credentials. That operator’s host acts for many end users, each with their own identifier, passed with --identifier. Confirm who each user is in your own app with user verification, and mint per-end-user Virtual MCP session tokens in your application, not inside Hermes.