Skip to content

Screeps Live API Integration

This document records the July 2026 investigation into connecting local or cloud development tools to the live Screeps MMO world.

The current repository already deploys with SCREEPS_TOKEN. Live integration should reuse that authentication model and should not change the deployment workflow unless a later implementation has a specific reason to do so.

Summary

Live integration is possible.

The best foundation is the existing screeps-api package in this repository:

  • Use HTTP endpoints for account metadata, shard metadata, current tick, memory reads, room snapshots, terrain, and explicit console command submission.
  • Use WebSocket subscriptions for live console output, console command results, CPU/memory updates, memory path updates, and room state updates.
  • Wrap those primitives in a small local Node service first, then expose a safe MCP server once the command surface is stable.

The Screeps Web API is not fully documented as a public API, but Screeps officially supports auth tokens for external tools. The official auth token docs state that undocumented HTTP endpoints are acceptable to use, that tokens can be sent with X-Token or _token, and that token-authenticated requests are rate limited.

Sources:

  • https://docs.screeps.com/auth-tokens.html
  • https://docs.screeps.com/commit.html
  • https://github.com/screepers/node-screeps-api#readme

Authentication

The existing SCREEPS_TOKEN works for live API communication.

Confirmed authentication methods:

  • X-Token: <token> works for HTTP endpoints.
  • The screeps-api client can use the same token for HTTP and WebSocket authentication.
  • GET /api/auth/query-token confirmed the local token has full access.

Do not print, commit, or paste SCREEPS_TOKEN into console expressions. Console transcripts and shell history should be treated as sensitive if they might contain secrets.

Confirmed HTTP APIs

The following HTTP endpoints were successfully exercised with the existing token:

  • GET /api/auth/me: authenticated account metadata.
  • GET /api/auth/query-token: token permissions.
  • GET /api/version: server metadata.
  • GET /api/game/shards/info: shard list, users, rooms, average tick duration, and recent tick durations.
  • GET /api/game/time: current game tick for a shard.
  • GET /api/user/world-start-room: active room lookup.
  • GET /api/user/world-status: account world status.
  • GET /api/user/memory: read memory paths.
  • GET /api/game/room-objects: room object snapshot.
  • GET /api/game/room-terrain: room terrain.
  • POST /api/user/console: queue a remote console expression.

Other useful endpoints exposed by screeps-api, but not all exercised during this investigation, include code branch reads/writes, user stats, room overview, market data, memory segments, and messages. Mutating endpoints should be guarded behind explicit workflows and should not be exposed as general-purpose tools.

Confirmed WebSocket APIs

The following WebSocket capabilities were confirmed or verified from the local screeps-api API surface:

  • User console stream via subscribeUserConsole.
  • Room state stream via subscribeRoom.
  • CPU/memory stream via subscribeUserCpu.
  • Memory path stream via subscribeUserMemory.
  • User code and resource streams are also exposed by the library.

Room stream caveat: the first room event can be a full snapshot with gameTime: null; later events are patch updates with gameTime. A consumer that wants current room state must maintain a local reconstructed object map.

Live Console

Live console reading is possible through WebSockets.

Remote console execution is also possible, but it is a two-step flow:

  1. Submit an expression with POST /api/user/console.
  2. Read the result from the user console WebSocket stream on a later tick.

The HTTP response to POST /api/user/console confirms that the expression was queued. It does not synchronously contain the evaluated return value. Results arrive through messages.results; ordinary bot logs arrive through messages.log; console errors can arrive through the console event error field.

Console expressions run in the live bot runtime after the main loop and consume runtime CPU. They can mutate the live game if the expression writes Memory, creates flags, destroys objects, or calls other mutating APIs.

Prototype Commands

These commands successfully communicated with the live Screeps world during the investigation. They are intentionally read-only.

npm run console -- "Game.time"

Observed result shape:

[shard3] < 81453800

npm run console -- "JSON.stringify({tick:Game.time, shard:Game.shard.name, rooms:Object.keys(Game.rooms), creeps:Object.keys(Game.creeps).length})"

Observed result shape:

[shard3] < {"tick":81453828,"shard":"shard3","rooms":["E48N13"],"creeps":10}

Read-only HTTP probing confirmed:

  • active room: E48N13
  • active shard: shard3
  • room object snapshot count: 334 objects at the time of the probe
  • terrain read succeeded
  • memory path stats read succeeded
  • shard info returned recent tick durations and average tick duration

A one-event room WebSocket subscription returned this shape:

{"type":"room","id":"shard3","path":"E48N13","gameTime":null,"objectPatchCount":334,"mode":"world","visualBytes":0}

Rate Limits

Auth-token requests are rate limited. Important published limits include:

  • global: 120 requests per minute
  • GET /api/user/memory: 1440 per day
  • POST /api/user/memory: 240 per day
  • GET /api/user/memory-segment: 360 per hour
  • POST /api/user/memory-segment: 60 per hour
  • POST /api/user/console: 360 per hour
  • GET /api/game/room-terrain: 360 per hour
  • POST /api/game/map-stats: 60 per hour
  • GET /api/user/code: 60 per hour
  • POST /api/user/code: 240 per day

Prefer WebSocket subscriptions for continuous observation. Use HTTP polling sparingly and cache responses when possible.

Limitations And Caveats

  • The Web API is mostly undocumented and may change.
  • Token-authenticated requests are rate limited.
  • Console execution is delayed until a game tick and depends on shard health.
  • Console results can interleave with normal bot logs and other console commands. Use unique markers to correlate command results.
  • Raw console execution is powerful enough to mutate or damage the live colony.
  • Direct Memory reads are too limited for high-frequency telemetry.
  • Room WebSocket updates are patch-based after the initial event.
  • The existing npm run live:check timed out once during the investigation and did not exit promptly until interrupted. Smaller read-only console expressions worked. Treat this as a script reliability issue to harden before relying on it for automation.

Use a small local Node service as the first integration layer.

The service should wrap screeps-api and expose narrow operations:

  • getAccountSummary
  • getShardStatus
  • getCurrentTick
  • getOwnedRooms
  • getRoomSnapshot(room, shard)
  • getMemoryPath(path, shard)
  • executeConsole(expression, shard)
  • watchConsole
  • watchRoom(room, shard)
  • watchStats

Once those operations are stable, expose them through an MCP server so Codex can use typed, permissioned tools instead of raw API calls.

Avoid making Codex call Screeps directly as the final architecture. A wrapper service gives one place for redaction, rate limiting, reconnects, audit logs, safe command allowlists, result correlation, and future metrics export.

Architecture Comparison

Direct API usage is simplest and is already enough for local scripts. It is not ideal as the long-term Codex integration because every tool has to reimplement token handling, rate-limit behavior, output redaction, reconnects, and console result correlation.

WebSocket subscriptions are best for live console logs, CPU/memory updates, room patches, and streaming Memory.stats. They are stateful and need careful reconnect behavior, but they avoid wasteful polling.

A small local Node service is the best near-term architecture. It preserves simplicity while centralizing safety and connection management.

An MCP server is the best Codex-facing architecture after the local service proves the command shapes. It can expose small safe tools such as screeps_get_tick, screeps_watch_console, or screeps_run_readonly_console.

Grafana or metrics exporters should consume Memory.stats through WebSocket memory subscriptions or a low-frequency bridge. They should not repeatedly poll full Memory.

Future Opportunities

Useful capabilities unlocked by live communication:

  • streaming console logs in the development environment
  • automatic deployment verification after npm run deploy:beta
  • remote read-only debugging with existing debug globals
  • room state queries without opening the Screeps client
  • current tick and shard tick-rate checks
  • health checks for spawn idleness, creep counts, CPU bucket, storage reserve, construction backlog, and maintenance pressure
  • Grafana integration fed by Memory.stats
  • performance metrics and CPU trend tracking
  • regression checks after behavior changes
  • alerting for repeated console errors, low energy reserve, stalled spawning, or missing critical roles
  • room-state snapshots for planning links, roads, maintenance, and remote rooms

Incremental Implementation Roadmap

  1. Harden the existing console tools with marker correlation, timeout cleanup, shard selection, and safer JSON parsing.
  2. Add read-only live tools for account summary, shard status, current tick, owned rooms, room snapshots, and memory path reads.
  3. Add streaming tools for console output, CPU usage, Memory.stats, and room patch subscriptions.
  4. Add deployment verification that waits for a later tick, runs a harmless console expression, and checks for console errors.
  5. Add colony health checks for population, spawn state, CPU bucket, room energy, construction, maintenance, and reserve policy.
  6. Build an MCP server over the stabilized local service.
  7. Add metrics export for Grafana-compatible storage.
  8. Add regression workflows that compare expected colony state after behavior changes and produce concise health reports.