neuro-sdk: the websocket API that lets a streamer control a game

What the repository actually contains

This repository contains the API documentation for allowing Neuro-sama to play games. Alongside the API documentation there are official SDKs for Unity and Godot, created and maintained by Alex, with pull requests welcome, and a set of example projects: open-source game integrations built with the Neuro SDK, including Slay the Spire 2, Inscryption, Buckshot Roulette as reference source code, Hollow Knight, Cyberpunk 2077 and Pokémon Platinum. There is also a directory for tools, and one tool in particular, Randy, which is a simple bot that mimics the Neuro API by making random actions and is meant for testing your integration before the real thing is connected. So the repository is three things at once: the protocol specification, the supported implementations, and a set of worked examples that show the shape of a working integration.

The protocol is a websocket, so any language can speak it

The important architectural fact is that the API is a websocket protocol. The README says there are official SDKs available for Unity and Godot as well as community-maintained SDKs, and that if you want to use the Neuro API in a different engine or programming language you will have to implement the websocket protocol yourself. If you do so, the project asks you to open a pull request to this repository to share your implementation with others by adding a link to the README. That request explains the size of the community list, which covers Rust, JavaScript and TypeScript, Java, Lua, Gamemaker, C, Python, Kotlin, C++, a generic C# SDK, Ren'Py, RPG Maker VX Ace and StarCraft II, plus separate server SDKs in JavaScript and TypeScript and in Python, the latter imported from a module called neuro_api.server. The server SDKs exist for people building a simulator server for testing purposes, which is a different use from playing a real game.

The games that work and the ones that do not

The Information section is the most valuable part of the README, because it sets expectations honestly. The official SDKs have been created and optimized for turn-based games, namely Inscryption, Liar's Bar and Buckshot Roulette. Games that require a non-low APM will generally not work well without Neuro only controlling the high-level actions and letting another system decide how to handle the low-level actions. Since you need to describe the entire game state in text, and receive actions in text, only games where that is feasible will work well with this API, and other games often require more complex solutions. The examples given for games that work well are Inscryption, Liar's Bar, Buckshot Roulette, Keep Talking and Nobody Explodes, Uno, Monopoly, most visual novels and most turn based card games.

Two different metrics decide whether a game is feasible

There are two constraints in that section and they are not the same thing. The first is the actions per minute, and the split between high-level and low-level actions is the practical advice: an agent that moves a character one square at a time cannot keep up with a real-time game, but an agent that chooses between doors and cards can. The second constraint is textual describability, which is the harder one. If a game has state that cannot be expressed as a description a text model can read and act on, no amount of action throughput helps. That is why the API shape matters so much: describing the entire game state in text, and receiving the actions in text, is the interface contract, and a game that does not fit that contract will fight the protocol rather than merely run slowly.

Randy for testing, and the tools built on the same idea

Randy is a simple bot that mimics the Neuro API, makes random actions, and can be used to test your integration. The point of that is to separate two kinds of failure: a bug in your game integration versus a bug in the model. With a random-action bot you can drive the whole loop, check that state descriptions arrive and actions are applied, and do it without an inference budget. The community tools take the same idea further. Tony is a graphical testing interface, similar to Randy, but it lets the user write messages manually. Jippity is a testing tool that aims to be a more realistic version of Randy by using OpenAI to mimic Neuro. Gary is another backend implementation for advanced use, originally created for testing with local LLMs like Llama, and it now also has support for a Randy-like random generator mode and a web UI for Tony-like manual sending. So the ecosystem has a deliberate ladder from nothing to a real model.

The community list comes with a caution attached

The community-maintained section opens with a caution callout and the wording is deliberate. The links are provided solely for convenience so that community members can find other implementations more easily, and the project does not review, verify or endorse any of the projects listed, and they may change or stop working at any time. Use any community-maintained SDKs, tools or code at your own risk, and the project does not take any responsibility for their functionality, security or reliability. The list is behind a details element with a summary of I understand. Click to expand and view list, which is a small design choice that signals the list is unvetted. For an evaluator, that means the count of ports says the protocol is portable, and nothing about whether any particular port is good.

Repository layout, changelog and versioning

The top-level listing shows where everything lives. There is an API directory for the documentation, a Unity directory and a Godot directory for the official SDKs, a Randy directory for the testing bot, an Assets directory with the icon, a CHANGELOG.md, a LICENSE.md and a README. There is also a Web Game Runner directory, which is the one name that suggests a piece of tooling rather than a sample. The changelog is the file to watch for API changes, since the README says significant API and SDK changes will be documented there, and the last update line records 1st of July 2026 at 12:45 GMT. The published release history here is thin, with a single tagged Godot SDK release from 2024-12-22, so the versioning of the API and of the SDKs is not obviously aligned, and the changelog rather than the tag list is the reliable signal of what changed.

Where neuro-sdk is the wrong choice

Four limits apply. It only fits games whose entire state can be described in text, which is a small set of turn-based designs and excludes most action games. The action rate ceiling means a fast game needs a hybrid architecture where the agent picks goals and something else executes them, and that is a system design problem the SDK does not solve. The official SDKs cover Unity and Godot only, so anything else means implementing the websocket protocol yourself, and the README asks for no tests against a reference implementation, which leaves you to validate the protocol against your own game. And the licensing of the ecosystem around it is uneven, since the project explicitly declines responsibility for the community ports and their security, so a production integration on a community SDK is a dependency you have to audit yourself.

Editorial conclusion

Use neuro-sdk when you are building a game you want a text-driven agent to play, because the protocol is a plain websocket with the state in text and the actions in text, and the official Unity and Godot SDKs remove the wiring work. Do not plan on it working for a fast action game, because the README states that games needing a non-low APM will generally not work well unless Neuro controls only the high-level actions. Verify first that your game can be described entirely in text, that the SDK you want exists or that you are prepared to implement the websocket protocol yourself, and that you have read the community list with the caution attached, since none of those projects is reviewed or endorsed.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. VedalAI/neuro-sdk on GitHub