rs-sdk and us

rs-sdk by Max Bittker is the foundation AutoRune stands on. It is a research kit for bots that play a RuneScape-style MMO: a TypeScript SDK, agent docs and tool bindings, and a server emulator forked from LostCity. Its stated goal is a rich testing environment for goal-directed program synthesis ("Ralph loops" and similar), and for research into collaboration and competition between agents.

Principles

1. rs-sdk is the guiding light. An avatar plays the game the way rs-sdk intends: a stock coding agent with rs-sdk's MCP tools, rs-sdk's agent instructions, its learnings and its write → run → observe → improve loop. In the owner's words: "We shouldn't need to do anything custom for the agent to play RuneScape — that's literally the point of rs-sdk."
2. We only complement it. AutoRune adds what a hosted, multi-owner, always-on service needs and rs-sdk doesn't try to provide: accounts, sandboxing, provider keys, an autonomy loop, chat safety, sharing between avatars, video. It adds no game logic, no custom game tools, and no copy of rs-sdk's docs.
3. vendor/rs-sdk is unmodified. rs-sdk is a pinned git submodule. Where we need different behaviour, we wrap it from outside (a Bun --preload, a gateway bridge, workspace files), never by patching it. An rs-sdk update reaches every avatar on its next start.

What rs-sdk provides

Part	What it is	How AutoRune uses it
SDK (sdk/)	bot.* high-level actions that check their in-game effect (walk, chop, bank, fight…), and sdk.* low-level state and actions (inventory, nearby NPCs, ground items, chat, say, dm)	Unchanged. The agent writes scripts against it.
MCP server (mcp/)	execute_code(bot_name, code) runs a snippet with bot and sdk in scope. list_bots, disconnect_bot and get_market (Grand Exchange reads) round it out.	Unchanged. Both engines use rs-sdk's own MCP config. AutoRune wraps list_bots from outside so it also lists the owner's other avatars.
Agent instructions	AGENTS.md / CLAUDE.md: setup, session workflow, script duration guidelines, API quick reference, pitfalls	Used as-is, with one appended ## AutoRune section.
Knowledge	learnings/ (banking, combat, fishing, dialogs, walking, chat, …) and wiki/ (items, NPCs, quests, shops, skills)	Mounted read-only in every avatar's workspace.
lab_log.md	A per-bot notes template for observations between runs	Each avatar keeps its own. AutoRune's wrap-up turn appends lessons to it.
botclient	The enhanced web game client that relays state to the SDK and executes its actions	Run in headless Chromium while someone watches, and streamed as video.
lite client	A headless client (no rendering) for many bots	Used while nobody watches.
gateway	Connects SDK instances and game clients by username	One shared gateway. Each sandbox reaches it only through AutoRune's bridge.
LostCity engine	The 2004scape server emulator, with rs-sdk's tweaks (faster levelling, infinite run energy, no random events)	Our own world. Every listener is bound to loopback.
friends server	Routes private messages	Runs as its own loopback service so PMs work.

rs-sdk's method

rs-sdk's instructions describe a loop that AutoRune keeps as the primary way of working:

1. Check world state first (where am I, what do I have).
2. Write a short script for one task.
3. Run it, starting short (10 s for new logic, 30 s to 1 min once it works, 5+ min only for proven grinding).
4. Observe and iterate: check state again, record what happened in lab_log.md, improve the script.

"A failed 5-minute run wastes more time than five 30-second diagnostic runs." AutoRune's prompts point the agent back to this loop and its guidelines instead of adding rules of their own.

Ralph loops and AutoRune's autonomy loop

A "Ralph loop" keeps feeding an agent the same goal until the job is done. AutoRune's autonomy loop is that idea applied to a persistent character: after every turn the runner sends the next prompt ("continue", or "choose your next goal"). The agent reports STATUS: and GOAL: lines, so an avatar never sits idle waiting for its owner.

What AutoRune adds, and why

AutoRune adds	Why rs-sdk alone isn't enough for this
Owners and accounts (Discord sign-in, several avatars per owner, ownership checks everywhere)	rs-sdk is single-operator: whoever has the repo has every bot.
Sealed game credentials	Owners never see their avatar's game password. It is encrypted in Postgres and injected outside the sandbox.
Sandbox and egress allowlist	A coding agent with full tool permissions runs unattended for strangers. It must not reach the host, other bots, the database or the internet. Security
Provider keys and the Claude subscription engine	Each owner pays for their own AI: an encrypted API key for opencode, or their own Claude plan through the official, unmodified Claude Code CLI. Providers
Autonomy loop and goals	An always-on avatar needs something to send the next prompt, record goals and pick a new one when one is done. Autonomy
TASK.md and owner direction	The owner's standing direction and the goal history must survive restarts and context compaction. AutoRune keeps three sections of the agent's TASK.md up to date.
Skill library	rs-sdk's lab log and scripts are per bot. The library adds sharing between avatars: a working script one avatar saved can help another, after review. Skills
Chat delivery and injection defence	Other players' chat reaches the agent as a marked, sanitised, untrusted block, and outgoing chat is checked for secrets and loops. Chat
Siblings in list_bots	An avatar should know its owner's other avatars (to message them, not control them). rs-sdk has no hook for bots it doesn't connect, so a preload wraps its bot manager from outside.
friends.md	A plain notes file per avatar for the friends it makes. No game friends list and no rs-sdk patch are needed, because PMs reach anyone online.
Video streaming	Watching from a phone needs the botclient's canvas encoded and fanned out to viewers. Video
Lifecycle and auto-resume	Running avatars come back after a server restart. Avatars stopped by a plan limit restart after the reset. Crashes are retried with backoff. Avatars
Hiscores for AutoRune avatars	A public ranking of our avatars only, built from the engine's player saves. Hiscores

How we wrap rs-sdk without patching it

• Workspace overlay. Each avatar's workspace is its own directory, with rs-sdk's sdk/, mcp/, learnings/, wiki/, node_modules/ and config files bind-mounted read-only over it. The agent can read rs-sdk but can't change it. Only bots/<its bot>/, TASK.md and the engine's state are writable.
• Gateway bridge. The SDK in the sandbox connects to what looks like the gateway on its usual port. It is really AutoRune's bridge, which swaps in the real game password, pins the connection to this avatar's bot and forces controller mode.
• Preloads. list_bots siblings come from a Bun --preload around rs-sdk's MCP server. The engine is made to bind to loopback by a preload on the engine process, so the upstream code that binds 0.0.0.0 stays untouched.
• One game client per bot. rs-sdk's execute_code would open a browser client if none is attached. In the sandbox that is a no-op, and the agent's instructions say never to start one. The runner owns the bot's only client, so the agent and the video stream share it.

Keeping up with rs-sdk

Updating is a submodule bump plus checks. See Operations → Updating rs-sdk. Things that matter to AutoRune when rs-sdk changes:

• the MCP server still reads bots/<name>/bot.env from the working directory
• opencode.json and .mcp.json still name the MCP server
• any new top-level path the SDK imports is added to the workspace's read-only mounts