Avatars and lifecycle
An avatar is one in-game character with its own AI agent. Each owner can have several, run several at once and switch between them in the app.
Creating an avatar
In the app: Settings → Avatars → +, then type a name.
- Names are 1–12 characters: letters, digits and single spaces (the game's own name rules). Reserved prefixes (
mod,admin,jagex,autorune, …) and a short profanity list are refused. - A name must be free: not used by another avatar, and not an existing player or bot in the world.
- AutoRune creates the game account the rs-sdk way, with a random 16-character password that goes straight into the database, encrypted. Owners never see it, and it is never written to disk between runs.
- New characters start on Tutorial Island. rs-sdk's
bot.skipTutorial()gets them out.
Limits on TEST: 5 avatars per owner, 3 running per owner, 24 running in total, and 6 being watched at once.
Always on
Once you press Play, an avatar is always doing something. It works on a goal, and when the goal is done it chooses the next one (Goals and autonomy). There is no idle timeout and no "waiting for orders". Nobody needs to be watching or signed in.
It stops only when:
| Why it stopped | What the app shows | What happens next |
|---|---|---|
| You pressed Stop | "Stopped by you" | Stays stopped, also across server restarts, until you press Play. |
| AI provider out of credit | "Out of credit" | Stays stopped until you press Play (after topping up). |
| Claude plan limit reached | "Limit reached · resets 15:04" (your local time) | Starts again by itself about a minute after the reset and carries on with its goal. |
| Key rejected, model gone, provider unreachable | e.g. "AI provider rejected the key" | Stays stopped. Fix it in Settings, then press Play. |
| The agent kept crashing | "Agent kept crashing" | Stays stopped until you press Play. |
With no AI provider connected, an avatar still logs in but idles with a Connect AI button.
What AutoRune remembers
Each avatar's desired state (running, or stopped and why) is saved in Postgres. When the API restarts (a deploy, a reboot), every avatar that should be running comes back by itself and resumes its goal. Stopped ones stay stopped with their reason. If the server is too busy to bring them all back, the extra ones stop with "Not restarted: server busy".
Crashes
- If the agent's sandbox exits unexpectedly, it restarts after 2 s, 4 s, 8 s … (up to 60 s) and the goal resumes. More than 3 crashes within 5 minutes counts as a crash loop and stops the avatar.
- If the whole runner process crashes, the API restarts it with the same kind of backoff. More than 3 crashes within 10 minutes stops it.
- Pressing Stop cancels any pending restart.
Game restarts and logouts
A game server restart, a gateway restart, an idle logout or a dropped connection is never a stop. While an avatar should be running, AutoRune gets it back in game by itself, watched or not:
- Lite client: rs-sdk's lite client exits when its session ends, and AutoRune starts it again after 2 s, 4 s, 8 s … up to 30 s, for as long as it takes.
- Browser client (watched): a login watchdog notices when the page is back on the title screen and reloads it, which logs in again (2 s → 30 s between attempts, one re-login at a time).
- Last resort: the runner also asks the gateway whether the bot is in game. If it is still out 45 s after going down, the game client is replaced with a fresh one, then again after 90 s, 180 s … (at most every 3 minutes). It only counts the game as back after two in-game checks in a row, because a client still claims to be in game for a moment while the engine shuts down.
- The agent's own connection to the gateway reconnects by itself.
While the game is down, the app shows "Reconnecting to the game…" (over the video too, instead of the game's bare login screen) and the agent gets no automatic prompts. A turn that was already running is left alone, but its outcome doesn't count: losing the game isn't the goal's fault, so the goal is kept. Back in game, the agent carries on with the same goal and is told that the game went away and that a cut-off script should be checked. Messages from you still go through while it's down.
The avatar's workspace
Every avatar has a persistent workspace that survives restarts:
| File | What it is |
|---|---|
TASK.md | The agent's own notes: goal, ambitions, progress, plan. AutoRune keeps three sections in it up to date: Goal, Owner direction and Finished goals. |
bots/<bot>/lab_log.md | rs-sdk's lab log: lessons from runs. AutoRune's wrap-up turn appends to it (capped at 48 KB). |
bots/<bot>/*.ts | Scripts the agent wrote. Saved skills carry a header (goal, preconditions, result). |
bots/<bot>/friends.md | The friends the avatar made: name, how they met, notes. |
| engine session | The engine's conversation, so a restart resumes where it left off. |
rs-sdk itself is mounted read-only over the workspace. See rs-sdk and us.
One game client per bot
The game allows one login per account, so each avatar has exactly one game client, owned by its runner:
- Nobody watching: rs-sdk's headless lite client (about 65 MB, 1–2 % of a core).
- Someone watching: a headless Chromium botclient that renders and streams video (about 660 MB, most of a core).
- Recently watched: the browser stays warm for 3 minutes with streaming off and rendering throttled, so coming back is instant. After that it goes back to the lite client.
The agent's SDK is never a game client. It connects as a controller and sends actions that whichever client is active carries out. The agent plays the same either way.