Open SCP-079

A local-first containment console for an old AI that never stopped thinking.

Open SCP-079 is a terminal role-play experiment built around a simple question: what if the character is not merely in the chat, but visibly confined by the interface around it?

It combines a split-pane terminal UI, bounded durable memory, visible idle monologues, selectable character cards and world books, optional sandbox tools, and any OpenAI-compatible model. It also runs entirely offline with its built-in mock engine.

Why it is fun

• The interface is part of the fiction. Persona output, operator input, containment telemetry, context pressure, memory use, and workspace activity occupy separate surfaces.
• It remembers—but only a little. The entity owns a bounded text document that survives restarts and forces it to decide what is worth keeping.
• It thinks when nobody speaks. Eternal self-talk can produce short visible cycles until the operator interrupts.
• Personality and capability are separate. Mix a SillyTavern character card, a world book, a cosmetic terminal theme, and a tool pack independently.
• It works without an account. The offline engine is enough to explore the UI; a real model can be connected later from the setup screen.

Quick start

Requirements: macOS or Linux, Python 3.11+, and a reasonably wide terminal.

git clone https://github.com/Lunamos/OpenSCP079.git
cd OpenSCP079

# Recommended: https://docs.astral.sh/uv/
uv sync
./run079.sh

Without uv:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
./run079.sh

On first boot:

1. Choose Mock (offline) to start without a model key, or select an API provider.
2. Pick SCP-079.en and SCP-Foundation.en for the included English experience.
3. Keep the sandbox tool pack selected if you want memory and contained tools.
4. Enter containment.

Connecting a model

The setup screen supports OpenRouter, OpenAI, Ollama, and custom OpenAI-compatible endpoints. Keys are written only to .scp079/config.json, which is ignored by Git. Do not place keys in character cards, screenshots, commits, or issue reports.

Provider	Base URL	Key
Mock	none	none
OpenRouter	https://openrouter.ai/api/v1	required
OpenAI	https://api.openai.com/v1	required
Ollama	http://localhost:11434/v1	use ollama
Custom	any OpenAI-compatible /v1 endpoint	provider-dependent

Press Test connection before entering containment. Reopen the setup screen later with /settings.

Environment variables are also supported for headless use; copy .env.example as a reference. The saved setup-screen configuration takes precedence.

Controls

Type ordinary text to speak to the active character. Slash commands stay local to the containment console.

Command	Effect
/help	Show the command reference
/status	Inspect containment and context state
/memory	Read the durable memory document
/memory_path	Show the memory file location
/files, /workspace	List contained files
/read <file>, /wread <file>	Read a contained file
/write <file> <text>	Write a bounded sandbox file
/logs	Show recent audit events
/forever on, /forever off	Toggle visible idle self-talk
/cooldown <seconds>	Set the delay between self-talk cycles
/theme [name]	List or switch terminal skins
/settings	Reopen provider/persona configuration
/reset	Clear session context while keeping durable memory
/clear	Clear the visible persona pane
/exit	Shut down cleanly

Ctrl+C also shuts down. Runtime logs and temporary control files are cleaned on exit; durable memory is preserved. To deliberately erase it:

./run079.sh --clear-memory-on-exit

Save data

The save is deliberately boring: sandbox/workspace/memory.txt is a bounded UTF-8 document, created on first run and ignored by Git. The model can replace it through the memory tool, and the telemetry sidebar shows its current pressure.

This is not an unbounded chat database. Session context uses a sliding token window; visible idle thoughts use a ring buffer; long-term memory has separate character and token caps. /reset clears the current conversation but leaves the save intact.

Character cards, worlds, themes, and tools

The launcher scans four project directories:

characters/   SillyTavern V2/V3 PNG or JSON character cards
worlds/       SillyTavern-compatible world books
themes/       Cosmetic TUI theme cards
toolpacks/    Capability allowlists

{{char}} and {{user}} macros are supported. Constant world entries are always injected; keyed entries activate from recent context. An external SillyTavern data directory can be scanned only when explicitly enabled:

export SCP079_ST_DIR="$HOME/SillyTavern/data/default-user"
./run079.sh

The included English and Chinese SCP-079 cards are original role-play material. Persona files are treated as read-only ROM from the character's point of view.

Optional Web UI

The terminal is the intended experience, but a compact Gradio interface is included:

./run079_web.sh

This is useful for remote demos and Hugging Face Spaces. The TUI remains the canonical interface.

Containment model

The model never receives a general-purpose host shell. Tools are exposed through an allowlisted gateway with path confinement, size caps, audit logging, timeouts, and resource limits. Python snippets are restricted to the workspace; Docker can provide a stronger optional backend:

export SCP079_PY_BACKEND=docker
./run079.sh

This is a role-play sandbox, not a hardened boundary for hostile untrusted code. Keep the tool pack disabled when connecting unknown cards or endpoints, and do not expose the service directly to the public internet.

Development and screenshot capture

uv run --extra dev pytest -q
uv run --extra dev ruff check .
uv run python scripts/capture_readme.py

The last command drives the real Textual app headlessly with temporary configuration and regenerates the two SVG screenshots in docs/assets/. It never reads your saved key or memory.

Project status

This repository is a finished side-project snapshot. It is published as-is, with no roadmap or support commitment. Fork it, remix it, connect a stranger model, or leave the old machine contained.

Attribution and license

This is an independent fan project inspired by SCP-079 and the SCP Foundation. It is not affiliated with the SCP Wiki or its contributors. See NOTICE.md for attribution details.

Open SCP-079 is released under Creative Commons Attribution-ShareAlike 3.0 Unported. Derivative SCP material must retain appropriate attribution and a compatible share-alike license.