VKodex: Open-Source VK Bot for Remote OpenAI Codex Control

What changed

VKodex is an open-source project designed to provide remote control capabilities for OpenAI Codex through the VKontakte (VK) messaging platform. This bot allows users to manage Codex tasks directly from their phones by interacting via VK messages and group chats. The system designates a personal VK dialogue as the manager for VKodex, while individual VK group chats are used to represent specific Codex tasks. Agent comments appear without notifications, and final responses are delivered as regular messages.

The current implementation is an experimental integration with Codex on Windows. VKodex manages a persistent App Server for each profile configured with owner: "app-server". However, a specific task's thread only gains temporary ownership during its execution and releases it after the final answer is confirmed. This design allows users to open a task in Codex Desktop or VS Code without encountering an "chat is open elsewhere" warning, as a new request from VK will reconnect to that specific task. If a task is already being controlled by Codex Desktop or VS Code, commands sent from VK will be routed to the confirmed owner in that client before execution. Automatic fallback is not provided once recording has begun. The Launcher is only invoked by an explicit /open command, preventing the application window from appearing unexpectedly during regular requests.

Compatibility with Codex's internal protocols is a consideration, as updates to Codex may alter these protocols. VKodex checks for compatibility at startup and during operation. Users are advised to begin by testing the bot on a non-critical task.

Why it matters for builders

For AI builders and developers, VKodex introduces a unique method for interacting with powerful AI coding tools like OpenAI Codex. It bridges the gap between mobile accessibility and complex development environments, enabling users to manage coding projects remotely. This could be particularly beneficial for developers who need to monitor, update, or initiate coding tasks while away from their primary workstation, fostering a more flexible and continuous development process.

Practical impact

To set up VKodex, users need a Windows computer with the Codex desktop application installed and authorized, running under the same user account. A working Codex authorization with access to at least one local project is required. The project recommends Node.js 24 LTS and npm 11.12.1, with Git for Windows for repository management. A VK account, a dedicated VK community under the user's control, and a community API key with message access are also necessary.

Network configuration involves separate routing: VKodex connects to the VK API directly via a Russian IP, while Codex/OpenAI traffic is routed through a VPN. This setup is typical for users in Russia.

Installation involves cloning the VKodex repository, installing dependencies using npm ci, and preparing the runtime executable. Configuration requires creating a .env file with VK community API keys and numerical IDs for the community and the user's personal VK account. Users must create a separate VK community, enable messages and group chat functionality, and configure Bots Long Poll with API version 5.199, enabling message_new, message_edit, and message_event types. A community access token with message permissions is crucial.

Finding the numerical IDs for the VK community and personal account can be done using the utils.resolveScreenName VK API method, which supports the community key. The project provides PowerShell scripts to assist with configuration and initial setup.

Caveats and source limits

The source material indicates that VKodex is an experimental integration with Codex on Windows. Support for other operating systems for live desktop connection is not stated. The compatibility of VKodex with future updates to Codex's internal protocols is subject to ongoing checks. The provided documentation focuses heavily on the setup and configuration process for Windows users and does not detail performance benchmarks or advanced usage scenarios beyond basic task management. Pricing for OpenAI Codex or any associated services is not mentioned, nor are specific performance metrics or limitations of the bot's remote control capabilities.