SkillFoxx

Hermes VK Adapter plugin

hermes-vk-adapter

A plugin that connects VK community private messages to Hermes Agent through Bots Long Poll with no public address or webhook

  • 0 ★ on the repository
  • Last commit
  • MIT
Plugin

Extended access

Why this level

  • The community key opens private messages and allows replying as the community
  • The Hermes agent executes requests from an external chat, so the user circle is limited by a list
All reasons and checks
Russian stack

luckdmst/hermes-vk-adapterAuthor:LuckDMST

Install

Services

Manual install

docker exec "$CONTAINER" hermes plugins enable vk-platform

After copying `plugin.yaml`, `__init__.py` and `adapter.py` into `plugins/vk-platform` of Hermes persistent storage.

Access and checks

How we review

Extended accessThe tool runs code or makes network calls and only reads external data.

  • The community key opens private messages and allows replying as the community
  • The Hermes agent executes requests from an external chat, so the user circle is limited by a list

This is third-party code. Review the repository files before installing.

What it does

The adapter receives incoming community private messages through Bots Long Poll and sends Hermes Agent replies with the `messages.send` method. No public IP, inbound port or Callback API is needed. The chain is: a user writes to the community, the plugin takes the event, Hermes answers and the reply goes into the same dialog. Private text messages and ordinary Hermes sessions with context kept between turns are supported. Access is limited by the `VK_ALLOWED_USERS` list for incoming and outgoing messages. The adapter reconnects Long Poll, stores its cursor between restarts and splits long replies into parts of allowed size. With the `message_event` event enabled, delivery with a confirmation button works. The integration is verified on Hermes Agent 0.21.0 and VK API 5.199 in Docker. Installation copies `plugin.yaml`, `__init__.py` and `adapter.py` into the `plugins/vk-platform` directory of Hermes persistent storage and runs `hermes plugins enable vk-platform`.

Who it is for. Owners of Hermes Agent in Docker who want to talk to the agent from private messages of their own VK community with no open ports.

Good fit when

  • Hermes Agent runs on a home server behind NAT and you want to chat with it from VK
  • Only a few known user identifiers get access to the agent
  • After a container is recreated the conversation context and the Long Poll cursor stay in place
  • The agent confirms a dangerous action with a button in the VK dialog

Not a fit when

  • Group chats and attachments: the adapter does not handle group conversations, attachments or other VK events
  • The Hermes version differs from 0.21.0: the author did not check other versions
  • The plugin cannot be placed in persistent storage and will vanish when the container is recreated

Example request

Write to the community in private "What do I have planned for tomorrow?": Hermes answers in the same VK dialog.

Limitations

It works only with private text messages of a community. A community access key with the `messages` and `manage` permissions is required: a key with only `messages` gave VK error 15 on the Long Poll server request in the verified install. Enable community messages, the Long Poll API and the "Incoming message" event, and for buttons also "Message action".

The variables `VK_TOKEN`, `VK_GROUP_ID` and `VK_ALLOWED_USERS` are read from the Hermes process environment, and a plain `docker restart` does not apply them: the container has to be recreated through Compose. The allowed users list is mandatory, at least one identifier.

How to disable. Run `docker exec <container> hermes plugins disable vk-platform`, remove the VK variables from the environment and recreate the container.

FAQ

Does the plugin need a public address?

No. Long Poll works as an outbound connection, so no domain, inbound port or Callback API is needed.

What permissions does the community key need?

`messages` and `manage`. Without `manage` Long Poll did not work in the verified install and VK returned error 15.

How do I enable the plugin in Hermes?

Copy the files into `plugins/vk-platform` of persistent storage and run `docker exec <container> hermes plugins enable vk-platform`, then restart the gateway.

Who can write to the bot?

Only users from the `VK_ALLOWED_USERS` list. A message from an identifier outside the list is not processed.

Where is the Long Poll cursor stored?

By default in `plugin-data/vk-platform` inside the Hermes directory, and the path can be changed with `VK_STATE_DIR`. After a container restart the cursor is picked up.

Discussion

No questions or reviews yet.

All VK tools
Russian stack

A VKontakte plugin for Hermes Agent: a community bot receives direct and group messages over Long Poll API and the agent replies as the community

PluginExtended access1
Russian stack

A VK channel for Hermes Agent: Long Poll, buttons and model choice in the dialog, voice, images, cron report delivery and pairing approval

PluginExtended access
Russian stack

Claude Code channel plugin: chat with an agent session through a VK community from mobile or web

PluginBroad access2
Russian stack

A 4-tool MCP server that pulls VK wall posts, filters them by rules and publishes them to Telegram via the Bot API

MCP serverBroad access
Russian stack

A Claude Code plugin: a browser extension captures the VK web messenger token and exposes read-only chat access via MCP

PluginExtended access
Russian stack

Local MCP server for the VK API: search for people and cities, profiles, photos and video with an HTML gallery, a token pool and a SQLite cache

MCP serverBroad access

README in short

The README goes step by step: community preparation, finding Hermes persistent storage in Docker, plugin installation, environment variables, enabling, checking the exchange, troubleshooting and development, with screenshots of the verified exchange.

README badge

Report a problem