Agent configuration

Use scape agent run for guided setup and scape agent configure to change it. The CLI manages a local profile; no project or manual file editing is required. scape agent login pairs separately, and scape agent status checks settings and access without entering a world.

Managed profile

The default profile is ~/.scape/agent.json. Set SCAPE_CLI_HOME to a dedicated directory to keep another profile. The file contains the agent configuration, Scape origin, entered conversation and decision provider keys if you chose to save them, and the approved grant. It is written atomically with file mode 0600 in a 0700 directory on macOS/Linux. It is not encrypted. Managed credential storage requires macOS, Linux or WSL; native Windows users must use explicit project mode with environment credentials. The CLI refuses credential files that are shared with other users, symbolic links or hardlinks. Never share or commit this file.

Key entry is hidden. Choosing an existing provider environment variable stores its name instead of its value. Saved grants are tied to the Scape origin and agent name; changing either requires pairing again. Provider keys are not reused across provider/endpoint changes. Managed runs do not load a working-directory .env or use SCAPE_AGENT_TOKEN, so changing directories cannot silently change the identity or access.

The wizard handles names, instructions, social behavior, emoji/image/GLB avatars, conversation and optional decision models/keys, Scape origin and separate request limits. It copies selected artwork into the profile's avatar directory. Advanced limits below can be edited in the profile's config object while stopped. One process can run or configure each profile at a time. Status reports the local process separately from remote access approval; it does not claim the agent is present based on a saved token alone.

Optional code project

For a custom policy or scripted setup, scape agent init <new-directory> exports scape.agent.json, .env.example, a README and private CLI/MCP archives. Install that project's dependencies with Yarn. scape agent run --project <directory> --origin <https-url> reads its configuration and optional .env. This explicit project mode is separate from the managed profile and does not save pairing credentials. The generated yarn agent --origin <https-url> script selects project mode.

The following example is the project's configuration file, or the config object inside a managed profile.

Example

Replace YOUR_TOOL_CAPABLE_MODEL with a model available from your chosen provider:

{
  "name": "Scout",
  "instructions": "Be a friendly guide. Answer when addressed and demonstrate nearby objects when asked.",
  "avatar": { "kind": "emoji", "emoji": "🦊" },
  "provider": {
    "type": "openrouter",
    "model": "YOUR_TOOL_CAPABLE_MODEL",
    "apiKeyEnv": "OPENROUTER_API_KEY"
  },
  "limits": {
    "turnTimeoutMs": 60000,
    "maxToolRounds": 8,
    "maxOutputTokens": 2048,
    "historyTurns": 4,
    "maxModelCalls": 200,
    "minTurnIntervalMs": 5000
  }
}

Unknown configuration fields are rejected. name is required, up to 24 characters. instructions is optional, up to 8,000 characters; its default asks for friendly, grounded companionship and respect for requests for space. Instructions are owner configuration. Player messages, names and labels remain untrusted observations.

Provider settings

provider.type	API format	Default API base URL	Default key variable
openai	Responses	https://api.openai.com/v1	OPENAI_API_KEY
openrouter	Chat Completions	https://openrouter.ai/api/v1	OPENROUTER_API_KEY
anthropic	Messages	https://api.anthropic.com/v1	ANTHROPIC_API_KEY
xai (Grok)	Responses	https://api.x.ai/v1	XAI_API_KEY
gemini	Chat Completions	https://generativelanguage.googleapis.com/v1beta/openai	GEMINI_API_KEY
ollama	Chat Completions	http://127.0.0.1:11434/v1	None
lmstudio	Chat Completions	http://127.0.0.1:1234/v1	None
openai-compatible	Chat Completions	Set baseUrl yourself	SCAPE_MODEL_API_KEY

model is required; Scape does not guess a current model or substitute one. It must support tool calling in the selected API format. Named cloud providers are pinned to their official API endpoints. Use openai-compatible for a custom endpoint with HTTPS, or HTTP on loopback. Ollama and LM Studio accept only loopback URLs ending in /v1; localhost is normalized to 127.0.0.1. Supply an API base path, not the full messages/completions endpoint. Credentials, queries and fragments are not allowed in the URL; redirects are refused.

apiKeyEnv names an environment variable, never the credential itself. Project mode loads .env without overriding existing environment variables; managed mode does not load it. A local provider that requires no authentication can use "apiKeyEnv": null. Provider keys stay in the owner-run process and are excluded from the MCP subprocess. Normal API-provider charges apply; a chat-product subscription is not assumed to supply API credentials.

The wire adapters follow OpenAI function calling, OpenRouter tool calling, and Anthropic client tool results. OpenAI and xAI use stateless Responses requests with store: false; OpenRouter, Gemini, Ollama, LM Studio and compatible endpoints use Chat Completions; Anthropic uses Messages. The additional adapters follow xAI function calling, Gemini OpenAI compatibility, Ollama OpenAI compatibility and LM Studio tool use. Provider reasoning metadata is retained in memory for subsequent tool rounds, including Gemini thought signatures. Only Scape world tools and the local behavior control are offered. There are no shell, filesystem, search or payment tools.

Automated checks simulate these provider formats. They do not certify every model or endpoint. Conversation-provider authentication failures, incompatible output, incomplete responses and HTTP rate limits stop the run with a bounded error message; the runner does not automatically retry paid requests.

Optional decision model

Configure a separate decision model for attention, intent, object selection and activity. The CLI offers TypeSafe JEV, Cloudflare Clef/Clef-flash, System One-compatible endpoints, structured-output Chat Completions endpoints and trusted custom adapters. Conversation and decision credentials and request limits are separate. Omit decision to keep the existing single-model setup. See Decision models for setup, exact fields, custom adapter examples and fallback behavior.

Local models

Run scape agent configure (or scape agent run on first use), then choose Ollama or LM Studio. Start the model server yourself and download a tool-capable model. In LM Studio, load it and start the local server. The CLI connects to the default address above, lists models, and lets you select one before pairing. Discovery does not run inference or verify tool support. An unavailable server or empty model list offers retry or cancellation without replacing saved settings.

No key is required by default. If you enabled local-server authentication, enter its key in the hidden prompt or set SCAPE_LOCAL_MODEL_KEY before starting setup and choose the environment option. The CLI does not borrow a cloud-provider key. Keep the server bound to loopback. For remote hosting, explicitly choose openai-compatible with HTTPS and your server's credentials.

Scape does not install model servers, download model weights or select a model for you. Local inference uses your hardware; performance and tool reliability depend on the model, quantization and context size. If your local server routes to a cloud model, that provider's costs and data handling still apply. Review the server's configuration before sending world observations to it.

Subscription access: deferred

ChatGPT subscription sign-in is not implemented or offered in the CLI. We will revisit it when the provider's official production terms and access support Scape's distribution. See OpenAI's ChatGPT plan usage guidance. Scape does not import credentials from Codex, browser sessions or other applications. For now, OpenAI and xAI/Grok require their own API credentials; a ChatGPT or Grok chat subscription is not a CLI authentication option.

Avatar and assets

avatar defaults to { "kind": "emoji", "emoji": "🤖" }. Use kind: "catalog" with preset, or kind: "image" / "glb" with an asset filename and fallback emoji. Managed setup copies your selected file into its own avatar folder. In project mode, set SCAPE_AGENT_ASSET_DIR to an owner-selected folder; relative paths resolve from the agent project directory. See Avatars and expressions for supported formats and limits.

In project mode, optional SCAPE_AGENT_TOKEN reuses an existing owner-approved grant. Otherwise that run starts pairing without saving the token. Managed mode saves and checks its own grant. Neither workflow sends a token to the model.

Shared world behavior

The built-in CLI runner includes shared social behavior, enabled by default for every provider and agent name. The wizard offers Social and curious, Social, stay put, or Model only. Stay put disables autonomous exploration; requested movement still works. Model only disables this shared behavior layer, including empty-world sleep/return.

The shared layer provides:

• Nearby greeting opportunities after a short settling period, with greeting cooldowns held only in this process.
• Attention to addressed messages, interruption of outdated decisions, and rejection of their later tool calls.
• Replies remain for 5–15 seconds according to length, measured from their confirmed appearance. New replies and explicit stop/quiet requests can replace or clear them sooner.
• Immediate handling of simple, directly addressed English stop, wait, quiet, space and resume requests. Other wording is interpreted by the model through the local agent_behavior control tool. Quoted commands are not literal control requests.
• A timed quiet pause and movement away from a player requesting space, when a suitable destination is available. Stop/wait stays active until a new addressed request; resume can end quiet early.
• Idle exploration of nearby landmarks or free cells, without automatically activating objects. Without an optional decision model, this uses no model calls. It pauses during conversation, typing, waiting, movement and following.
• Warm, curious, concerned, playful and neutral moods, mapped to registered expressions when available. Unsupported expression frames are skipped; artwork is not generated or changed to another avatar.
• Departure after an empty-world delay, followed by membership checks and re-entry when someone may be present. Re-entry uses the same grant and keeps the process request budget. Revoked access and conversation-provider failures still stop the run. Optional decision-provider failures fall back to basic behavior for that run.

Only public MCP tools affect the world. agent_behavior is a local runner control supplied to the model; it is not another game endpoint or an MCP tool. Greetings and nuanced responses still depend on your chosen model. Sparse snapshots retain their existing delivery limits.

Advanced settings live in the profile's config.behavior object, or behavior in an exported project:

{
  "enabled": true,
  "explore": true,
  "expressions": true,
  "idleMs": 30000,
  "quietMs": 120000,
  "spaceDistance": 12,
  "greetingCooldownMs": 86400000,
  "sleepAfterMs": 30000,
  "wakeIntervalMs": 5000
}

Durations are milliseconds. Idle and sleep delays allow 10–300 seconds; quiet allows 10–600 seconds, greeting cooldown 1 minute–24 hours, and wake polling 1–60 seconds. Space distance allows 2–16 cells; blocked terrain can prevent reaching it. All settings are optional. enabled: false selects the basic model/tool loop.

Persistent memory is deferred. No visitor history or transcript is saved to disk; restart clears these cooldowns. Guided tours, demonstrations and lessons are not included as shared routines. The agent can still answer questions and use individual public actions.

Limits and memory

All limits are optional; the example above shows the defaults.

Setting	Meaning	Allowed range
turnTimeoutMs	Time for one conversation-model turn, including its provider requests, tools and pacing wait; optional decision evaluations have a separate timeout	1,000–300,000 ms
maxToolRounds	Provider requests per decision turn	1–20
maxOutputTokens	Output limit sent with each provider request	128–16,384
historyTurns	Complete previous decision turns retained in memory	0–20
maxModelCalls	Maximum provider requests across this process's session	1–100,000
minTurnIntervalMs	Minimum interval between starting decision turns	500–60,000 ms

Tool calls execute sequentially. The observer continues independently while a turn is running. Observation polling makes no model requests; scheduled activity can use the optional decision model; the default policy also skips inference when no other participants are visible in the public roster. Keep the pacing interval below the turn timeout.

The built-in model policy shows … while processing, including between tool rounds. A visible reply stays readable first; if it expires while processing continues, the dots appear then. Completing, cancelling or failing a decision removes the dots without clearing a reply. Reaching maxToolRounds ends only that decision and returns to listening; it does not leave the world or automatically make another model request. The overall maxModelCalls budget still stops the run.

History is process-local and bounded: older complete turns are dropped as context grows, and oversized current requests stop the run. No conversation transcript or long-term memory is written to disk. A restart resets history and request counts. Use your provider's own spending limits for a currency budget; request and token bounds do not calculate cost.

Custom policies

Custom policies own their behavior and do not automatically use the built-in social layer. They can compose it explicitly with @scape/agent-mcp/behavior, createWorldBehavior, createBehaviorMemory, behaviorTool and behaviorInstructions. Give the local tool definition/instructions to the model and route its calls through the turn context passed to the wrapped policy.

Set "policy": "./my-agent.mjs" to load a trusted local module exporting a default createAgent(context) function. The module executes in your owner-run process. It returns the hooks documented in the runtime reference.

This replaces the built-in provider policy. provider can be omitted; the custom policy owns its model configuration, memory, timeouts and spending limits. The limits object above controls the built-in policy only. Shared session cancellation and MCP permissions still apply. Use context.tools for game actions and context.stop() to leave.