Self-hosted agent runtime.

Spore is a self-hosted AI agent runtime for people building tools with tools. It combines a web control panel, model routing, plugin-loaded tools, channel gateways, scoped graph memory, and a coding client that executes local tools where your files actually live.

Spore has three main faces:

• Spore Core is the server. It runs the agent loop, web UI, settings, plugins, queues, graph memory, channel gateways, learners, browser backends, and APIs.
• Spore Code is the terminal client. It connects to Core over HTTP/WebSocket and owns local tools such as file edits, shell commands, code indexing, background processes, and git helpers.
• Spore Go is the Expo / React Native companion. It signs into Core, lists sessions, observes activity, and lets you continue web or coding sessions from a phone.

The important design choice is scoped memory. A web user, a coding project, and a Telegram chat should not all pollute one global prompt. Spore writes to the graph that belongs to the current user, project, or channel, while shared reusable lessons are promoted into General Knowledge.

Bring up Spore in three pieces: Core is the server, Code is the terminal client that runs in your project, and Go is the mobile companion.

1. Run Spore Core

The fastest path is the Docker Hub image. Start the container, open the web UI, and finish the first-run wizard.

docker run -d --name spore --restart unless-stopped \
  -p 18803:18803 -p 127.0.0.1:18790:18790 \
  -v spore-data:/data -v spore-workspace:/workspace \
  -e SPORE_WEB_PORT=18803 \
  -e SPORE_HEALTH_PORT=18790 \
  -e SPORE_DATA_DIR=/data \
  -e SPORE_WORKSPACE_PATH=/workspace \
  -e SPORE_PLUGINS_ENABLED=true \
  vibecoalition/spore-core:latest

Open http://localhost:18803. The wizard creates the first operator account, writes settings under /data, and lets you pick providers, model routes, plugins, and theme.

2. Install Spore Code

Spore Code is the terminal client. Install it on the machine where your repository lives, then run spore from a project directory.

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/Vibe-Coalition/spore-code/main/install.sh | sh

# Windows PowerShell
irm https://raw.githubusercontent.com/Vibe-Coalition/spore-code/main/install.ps1 | iex

On first launch, the setup wizard asks for the Core URL, username, and invite key or password. It exchanges those credentials for a device token and stores local settings under ~/.spore-code.

cd path/to/your/project
spore        # start or create a project session
spore --plan # start in plan mode
spore -c     # resume a previous session

3. Install Spore Go

Spore Go is the Android companion app for checking sessions, answering questions, approving plans, and talking to your own web graph from a phone.

Until the Play Store listing is live, the clean user path should be a signed APK attached to Spore Go releases. Developers can also run or build the Expo app from source.

git clone https://github.com/Vibe-Coalition/spore-go.git
cd spore-go
npm install
npm start

From the Expo prompt, open Android, web, or an emulator target. If Android tooling is installed locally, this also works:

npm run android

Maintainers should publish a signed APK for sideloading now, and an Android App Bundle when the Play Store release is ready.

# Suggested maintainer release flow
npx eas-cli build --platform android --profile preview     # APK for GitHub Releases
npx eas-cli build --platform android --profile production  # AAB for Play Store

• Host: Docker on Linux, Unraid, macOS, or Windows. Core itself runs as a Linux container.
• Memory: 4 GB minimum, 8 GB or more once browser automation, embeddings, voice, and code indexing are active.
• Disk: leave headroom for /data, graph backups, embeddings, browser state, and benchmark clones.
• Network: outbound HTTPS to model providers and any enabled integrations. Expose the web port only behind auth, LAN, VPN, or a reverse proxy you control.

For production, use Compose and keep each instance in an isolated folder. Mount /data for durable settings, graph DBs, sessions, credentials, plugin state, and backups. Mount /workspace for files the agent creates or serves.

services:
  spore:
    image: vibecoalition/spore-core:latest
    container_name: spore
    restart: unless-stopped
    env_file:
      - ./.env
    ports:
      - "18803:18803"              # web UI, API, websocket
      - "127.0.0.1:18790:18790"    # health endpoint
    volumes:
      - ./data:/data
      - ./workspace:/workspace

Useful environment variables:

SPORE_WEB_PORT=18803
SPORE_HEALTH_PORT=18790
SPORE_DATA_DIR=/data
SPORE_WORKSPACE_PATH=/workspace
GRAPH_DB_PATH=/data/graph.db
SESSION_DB_PATH=/data/sessions.db
SETTINGS_DB_PATH=/data/settings.db
SPORE_PUBLIC_URL=https://spore.example.com
SPORE_PLUGINS_ENABLED=true
SPORE_LOG_LEVEL=info

SPORE_PUBLIC_URL is optional, but set it when Core is behind a public reverse proxy. It is used for served web apps, callbacks, and links shown to users.

A fresh instance starts with an onboarding wizard. It creates the first operator, chooses the default theme, configures model providers, installs selected plugins, writes settings to /data/settings.db, and creates the initial graph layout.

Plugins installed through onboarding register their settings and reference nodes immediately. Reference nodes install into General Knowledge so the agent can learn how tools work without polluting the default graph.

Spore settings are layered. Environment variables and first-run files seed the instance, then runtime settings live in /data/settings.db. The settings panel supports search and plugin-provided sections.

Main setting groups include:

• identity, paths, web ports, public URL, and auth;
• model providers, model library, routing presets, and tiers;
• embeddings, enhanced recall, learner activation, and queues;
• channels, privacy, proactive behavior, and wakeups;
• browser backend, voice, web search, Tailscale, SSH, backups;
• theme, graph renderer options, logs, plugins, and security.

The first onboarded account is the operator. Additional web users can have their own user graphs and can be granted access to default, General Knowledge, and projects they collaborate on.

• Web sessions use server-side auth and HttpOnly cookies.
• Spore Code and Spore Go authenticate with an account password or a revocable invite/device key generated from Core.
• Spore Code can inherit server routing or apply a device-local default routing override without mutating other users.
• Stale WebSocket sessions should not keep users locked out; valid login attempts are allowed to recover from expired connections.

Spore uses SQLite-backed graphs instead of one global memory pile. Graph switching in the UI changes what the user is viewing and what future graph-scoped actions should target.

• default is the instance/default graph.
• spore-knowledge-base is General Knowledge: shared reusable lessons, plugin reference nodes, and stable facts.
• user-* graphs hold private webapp user memory.
• project-* graphs hold Spore Code project memory and can be shared by collaborators on the same project.
• channel-* graphs hold Telegram, Slack, Discord, and other channel/person memory.

Project and channel graphs can read General Knowledge. Durable, non-private lessons can be distilled back into General Knowledge; personal reminders, recurring jobs, channel context, local hostnames, and project secrets should stay scoped.

The learner extracts useful facts from turns and writes them to the current session’s graph scope. Distillers summarize longer arcs and promote reusable lessons to General Knowledge when appropriate.

Important controls:

• SPORE_LEARNING_MODE: always, flush_only, or disabled.
• SPORE_LEARNER_ACTIVATION_MODE: every_turn or idle_batch.
• SPORE_LEARNER_IDLE_DELAY_SECONDS, SPORE_LEARNER_BATCH_MIN_TURNS, and SPORE_LEARNER_BATCH_MAX_TURNS tune batching.
• SPORE_LEARNER_ENABLED_PLATFORMS limits platforms that can trigger learning.
• enhancedRecall lets a model decompose the request into multiple recall queries. It is useful, but not a substitute for correct graph scoping.

Providers are plugin-owned. Installing or removing a provider changes which models appear in routing choices.

• Anthropic: ANTHROPIC_API_KEY.
• OpenAI Responses: OPENAI_API_KEY and optional OPENAI_BASE_URL.
• OpenRouter: OPENROUTER_API_KEY.
• Gemini: GEMINI_API_KEY; also feeds the Gemini embedder.
• Z.ai / GLM: ZAI_API_KEY.
• Local/custom OpenAI-compatible endpoints: LOCAL_MODEL_BASE_URL, LOCAL_MODEL_API_KEY, or structured custom providers.

Spore routes different work to different model tiers. Configure them in Settings or with environment variables.

• SPORE_CASUAL_MODEL: quick replies and light work.
• SPORE_NORMAL_MODEL: main agent loop and tools.
• SPORE_PLANNER_MODEL: plans, hard reasoning, summaries, benchmark analysis, and advisor calls.
• SPORE_SUBAGENT_MODEL: delegated workers.
• SPORE_LEARNER_MODEL: extraction and distillation.
• SPORE_RECALL_MODEL: enhanced recall decomposition.
• SPORE_IMAGE_VLM_MODEL, SPORE_VIDEO_VLM_MODEL, and SPORE_AUDIO_VLM_MODEL: media analysis.

Routing presets can be changed from the web app. Spore Code users can switch presets locally; a device-local override should not overwrite server-wide defaults.

The planner advisor is a planner-tier assist that can guide a weaker or chattier execution model. It is enabled by default and can run adaptively, always, or off.

• plannerAdvisor.enabled toggles the feature.
• plannerAdvisor.mode: adaptive, always, or off.
• plannerAdvisor.maxInputTokens and plannerAdvisor.maxOutputTokens cap advisor context.
• plannerAdvisor.cooldownIterations prevents spam.

Core emits advisor activity so you can tell whether it fired. Use aggressive planner involvement when you want extra review around long coding sessions, but keep execution alive rather than killing the turn just to close out.

Any OpenAI-compatible endpoint can be used as a local provider. Ollama, vLLM, LM Studio, and llama.cpp server are the common paths.

# Example with Ollama exposed to the container
LOCAL_MODEL_BASE_URL=http://host.docker.internal:11434/v1
SPORE_NORMAL_MODEL=local/llama3.2:8b
SPORE_PLANNER_MODEL=openrouter/anthropic/claude-sonnet-4.5

Smaller local models can work for chat and simple tools. For long coding sessions, use a strong planner tier to guide the cheaper normal tier.

Tools are exposed by session type, plan/execute mode, plugin state, and availability callbacks. A tool should be hidden before the model sees it if the current channel cannot safely use it.

• Core tools include graph operations, web search/fetch, message tools, wakeups, tasks, log watches, media analysis, settings, and multi-spore calls.
• Spore Code local tools include read_file, edit_file, write_file, exec, grep, glob, code index tools, background processes, and git helpers.
• The browser and webapp_request tools are hidden from CLI sessions and scoped to the requesting web/channel user.
• Cron guidance is server-side and hidden from CLI sessions.
• ask_user is for concrete choices in web and Spore Code sessions. Normal text while a question is pending should supersede or cancel the pending picker, not disappear.

The web_serve tool mounts generated apps under unique paths. For a new site, write files under /workspace/web/<name>/, call web_serve with that name, and share the returned mounted URL.

# Static app convention
/workspace/web/hello-world/

# Returned URL shape
/serve/hello-world/

The agent should not give users the bare Spore root or server IP as the app URL. If SPORE_PUBLIC_URL is unset, share the relative mount path. Use webapp_request for HTTP checks against served apps.

For backend apps, web_serve action:"backend" allocates a port, injects vault keys as environment variables, proxies routes, and persists the backend across restarts.

Spore Code is installed from the Vibe Coalition repository and the binary is named spore.

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/Vibe-Coalition/spore-code/main/install.sh | sh

# Windows PowerShell
irm https://raw.githubusercontent.com/Vibe-Coalition/spore-code/main/install.ps1 | iex

Common commands:

spore                         # new session in this directory
spore -c                      # resume a previous project session
spore --session cli:...       # resume a specific session
spore --plan                  # start in plan mode
spore logout                  # clear saved credentials

Spore Code sends project context separately from user chat: project name, cwd, git state, shallow tree, SPORE.md, runtimes, OS/arch, plan/execute mode, scope mode, code-index status, and local tool availability. That context should help the model act in the current repo without leaking the rest of Core.

• Plan mode: read, research, ask blocking questions, and propose a plan. Mutating tools are blocked until execution is approved.
• Execute mode: run approved local tools and server tools. Approval modes are auto, ask, locked, yolo, and rules.
• Project graph: the same project should resolve to the same stable project-* graph for the same or collaborating users.
• Compaction: Core can emit context pressure and compaction status so the TUI can show when context is being summarized.

Spore Go is the Expo / React Native companion for mobile, web, and emulator targets.

git clone https://github.com/Vibe-Coalition/spore-go.git
cd spore-go
npm install
npm start

First launch asks for the Core server URL, username, and password or invite key. It stores credentials/token data, fetches available sessions, and opens a realtime WebSocket for chat, tool status, plan approvals, questions, and notifications.

A mobile "web graph" session should talk to that user’s own web/user graph. A mobile coding session observes or controls a real Spore Code session only when that CLI session is connected and authorized.

Telegram, Slack, and Discord are bundled channel plugins. Channel sessions are first-class: they keep platform, channel/chat ID, user ID, graph slug, wakeup origin, and learning scope.

• Telegram supports DMs, groups, forum topics, attachments, reactions, recent-message recall, and voice-note transcription when voice providers are configured.
• Slack uses Socket Mode for channels, DMs, mentions, threads, files, reactions, and task progress.
• Discord supports channels, DMs, replies, reactions, attachments, task progress, and optional voice behavior.

Pairing should be approved from plugin settings where possible. A human Telegram login code is not a bot pairing code and should not be pasted into Spore. Recurring channel jobs must send back to the originating channel, not the web app or a random active CLI.

Plugins can add tools, providers, gateways, routes, static UI, settings, prompt sections, workers, browser backends, and reference nodes. They run as trusted Node.js code in Core, so only install plugins you trust.

Bundled plugin groups:

• Models: Anthropic, OpenAI, OpenRouter, Gemini, Z.ai, local/custom OpenAI-compatible endpoints.
• Memory: local Gemma embeddings, Gemini embeddings, session-graph, LongMemEval, Spore Code benchmark.
• Browser: browser-core, Zendriver, Playwright.
• Channels: Telegram, Slack, Discord.
• Media and voice: Deepgram, Whisper, ElevenLabs, FLUX.
• Operations: email, Tailscale, SSH sidecar, compute cluster, cron runtime guidance, Spore Code.

Plugin reference-node SQL installs into General Knowledge and is removed on uninstall when the plugin owns those rows.

Backups and export/import are graph-aware. Operators should always know whether they are exporting default, General Knowledge, a user graph, a project graph, or a channel graph.

• SPORE_BACKUP_ENABLED toggles graph backups.
• SPORE_BACKUP_INTERVAL_MINUTES controls cadence.
• SPORE_BACKUP_RETENTION controls retention count.
• SPORE_BACKUP_DIR changes the backup directory.
• SPORE_BACKUP_ON_CHANGE_ONLY skips unchanged graph backups.

The global reset action preserves only default and General Knowledge, resets both, and removes other graph DBs. Individual graph reset actions apply only to the selected graph.

Tailscale and SSH are optional operational features. Tailscale requires SPORE_TAILSCALE_ENABLED=true and a running tailscaled daemon inside the container. The hostname can be set from plugin settings.

SSH works with local encrypted fallback or the optional SSH sidecar. The sidecar isolates saved-host CRUD, interactive SSH, remote exec, and SFTP from the main process when deployed.

Spore includes evaluation plugins for memory and coding behavior. They are meant to reveal regressions in execution, graph scoping, memory handoff, setup behavior, and leakage.

• Spore Code Benchmark: simulated coding sessions across public repositories, multi-turn actor conversations, multi-user project handoff, verification commands, memory settle checks, LLM summaries, and leakage scanning.
• LongMemEval: long-memory benchmark in an ephemeral graph so runs do not pollute real memory.

Benchmark actor identities and task noise should not land in the default graph. Reports should keep transcripts compact enough for review while preserving final messages, tool outcomes, failures, and verification evidence.

Spore is an operator-grade surface. It can run shell commands, edit files, store credentials, open browsers, connect to private networks, and load unsandboxed plugin code.

• Protect the web UI with auth, VPN, LAN controls, or a proxy.
• Keep the health port bound to localhost unless monitored.
• Only install plugins you trust.
• Use credential guard and redact secret settings in UI reads.
• Back up /data before destructive graph actions.
• Treat Spore Code local execution as powerful: approval mode, scope mode, and project trust matter.