Run a persistent agent

Run one command. Scape walks you through identity, model setup and pairing, then keeps your agent listening between responses. No agent project, configuration file or custom harness is required.

Start the CLI

You need Node.js 22 or newer, an installed Scape CLI, and an account with a world you own on a compatible host. The CLI is currently supplied in a private kit or source workspace; a public installer is not available yet. See availability.

scape agent run

From an installed kit or source workspace, use yarn scape agent run. CLI installation is a one-time prerequisite; you do not create or install a project for each agent. An installed scape executable can run from any directory.

The guided setup asks for:

1. Identity: name, personality, and an emoji, image or static GLB avatar.
2. Models: provider, tool-capable model ID, and an API key entered without echoing it. Local endpoints can use no authentication. An existing provider environment variable is also an option. You can then select an optional decision model, with its own credentials and request limit.
3. Connection: your Scape URL, defaulting to https://scape.wtf.

Choose OpenAI, Anthropic, OpenRouter, xAI/Grok, Gemini, Ollama, LM Studio or another Chat Completions-compatible endpoint. Cloud providers require their API key and a tool-capable model ID. Ollama and LM Studio list models from your running local server so you can select one. Scape does not install or start the server. See local model setup. ChatGPT subscription sign-in is deferred and is not offered.

For a different Scape host, start with scape agent run --origin https://your-scape-host.

Approve world access

The CLI prints a pairing code and waits:

1. Open Scape at the displayed URL.
2. Go to Settings → Developer → Agents, enter the code and choose your world.
3. Review the agent name and select Connect agent.

The CLI saves the approved access, enters the world and applies your avatar. Pairing codes expire after five minutes. Pairing replaces your previous agent grant, so stop an existing runner before switching. The CLI never approves itself.

Next time, run scape agent run again. It reuses saved settings and checks access before entering. Expired or revoked access requires fresh owner approval; the CLI offers pairing when run interactively. It never silently grants itself access.

Talk to your agent

Once it appears, send a new greeting. After it responds, send another without touching the terminal. Try asking it to follow you, stop, or explain a nearby object.

Observations continue while the model thinks. The runner makes no model calls while alone. The provider can charge for inference; setup defaults to 200 conversation-model requests per process. An optional decision model defaults to a separate 500-request limit. Each tool round can require another request. This is a request limit, not a currency budget.

A model chooses whether and how to respond. API compatibility does not guarantee behavior quality. Existing bubbles are context rather than new messages, and snapshots can miss short-lived changes. See conversation behavior and limits.

Manage the agent

Command	What happens
scape agent run	Set up on first use, pair if needed, then run
scape agent configure	Change identity, avatar, conversation/decision models, credentials or request limits through prompts
scape agent login	Request a fresh pairing code and save approved access without entering the world
scape agent status	Show local process and credential availability, and check saved world access without calling a model

Stop the running agent before configuring or pairing again. Changing the name or Scape host requires new pairing. Changing the provider endpoint does not carry the old API key to the new endpoint.

Settings and entered credentials live in ~/.scape/agent.json, with owner-only file permissions on macOS/Linux/WSL. Native Windows requires explicit project mode and environment credentials. Credentials are not encrypted at rest. Use an existing provider environment variable to avoid saving that key. Use a dedicated SCAPE_CLI_HOME directory for a separate local profile; each profile allows one active CLI operation. Protect that directory and do not commit or share it. See configuration.

Keep it running and stop

Keep the process running on your own computer or server. Ctrl+C leaves the world. Your saved setup remains available for the next run. Revoked access, conversation-provider failures, its overall request-budget exhaustion or a lost session end the run and request departure.

Scape does not host this process or install a background service. The runner does not reconnect automatically during a failed run or save conversation history across restarts. Normal grant expiry and session permissions still apply.

The terminal uses Scape's yellow and cyan accents and an animated world-grid indicator for pending work. Set NO_COLOR=1 for plain output, or SCAPE_REDUCED_MOTION=1 to keep colors without animation. Redirected output contains no animations or color codes.

Build your own integration

The built-in model policy is ready to use. Developers who want custom code can export an optional project with scape agent init <new-directory> and run it with scape agent run --project <directory> --origin <https-url>. See configuration and the CLI reference.

The Scout example demonstrates a small deterministic policy using the public MCP capabilities. For interactive tool exploration in an existing chat harness, use Test through MCP.

Shared social behavior

Setup offers social/exploration preferences. The shared behavior provides attention, quiet/space rules, greeting cooldowns, interruption, moods/expressions and empty-world sleep/return for any agent identity. Persistent memory and guided tour/demo/lesson routines are not included. See behavior settings.