/docs
Guide
Spark Agent Docs

Set up Spark without guessing.

A practical guide for installing Spark, choosing your model, turning on Spark Live, and checking Telegram, memory, and missions.

updated: 2026-06-23
Guided installer Open the visual install tutorial. Start here if you want Codex, Claude Code, Cursor, or another setup assistant to walk through the install with you.

Start here if you want the smooth path.

The easiest install is not copying a terminal command alone. Ask an AI coding assistant like Codex, Claude Code, or another assistant that can read docs and run terminal commands to open agent.sparkswarm.ai and install Spark with you.

You can still install Spark yourself from the install page. If you are non-technical, start with the assistant-guided path first. It can choose the right Mac, Linux, WSL, or Windows command, run the safety preview, and explain each setup choice.

Spark gives you a Telegram chat door, memory, Spark Live, Spark Researcher, Spark Intelligence Builder, and Mission Control. You can talk to it, save what matters, research ideas, start builds, and watch work move through Kanban and Canvas.

The self-improving part comes from domain chips: reusable skills Spark can build, test, and reuse. With the right chip, Spark can practice a workflow even while you are away and come back with visible progress instead of vague promises.

Public builder labs are available now for experiments: Spark Domain Chip Labs, Spark Character, Spark Personality Chip Labs, and Spark Voice Comms. Spark Swarm network submission is not a public installer dependency yet.

Before installing, choose how Spark should reach an LLM. If you already use Codex or Claude Code, start there. If you prefer API keys, Spark can use Z.AI GLM, Kimi, MiniMax, OpenRouter, DeepSeek, Hugging Face, or another supported provider.

Keep the first setup simple: one provider can power both Agent and Mission. Split chat/memory from build work only if you already know you want different models for those jobs.

Run the dry-run before the real install. It shows the files, repos, versions, checksums, and commands before anything is written to your computer.

Local models are possible too. Start with Gemma 4-class models on smaller machines, or try larger local coding models such as Qwen 3.6 27B if your computer is stronger.

Read The May 14 Update Installer refresh, public labs, character, personality, and voice boundaries. Start With The Guide The calm walkthrough: assistant, model, BotFather, first chat, and Mission Control. See The Safe Install Path Download, verify, dry-run, install, then check that Spark is working. Choose Your Model Use one provider for Agent and Mission, or split chat/memory from build work. Run Spark Always-On Use Railway or a VPS for hosted Telegram, Mission Control, and production smoke checks.

After Spark is installed, use Turn Spark On, Learn Commands, Host Spark, or Fix Something when you need them.

Spark Suites

What gets installed, in human words.

The default bundle is called telegram-starter. Think of it as the normal Spark starter kit.

The public installer stays conservative: it installs the stable starter modules. Domain chip labs and personality chips are public builder surfaces, but they are not automatic starter-bundle modules yet. Voice is opt-in through telegram-voice-starter.

Chat Door

Spark Telegram Bot

Talk to Spark from Telegram without opening a dashboard.

BotFather creates the token. Spark keeps it local.

Runtime

Spark Intelligence Builder

Routes Agent and Mission work to your chosen provider.

Connects memory, tools, and setup roles behind the scenes.

Memory

Domain Chip Memory

Spark's starter memory layer for facts that should stick.

Saves and recalls useful context when memory is enabled.

Missions

Spawner UI

Mission Control for builds, research, coding, and bigger work.

Starts, tracks, and manages progress without losing the thread.

Research

Spark Researcher

Helps Spark gather evidence before it answers or builds.

Use it when the work needs context instead of guesses.

Identity

Spark Character

Keeps Spark's role, voice, and permissions steady.

Helps the agent explain its limits without overreaching.

Public Labs

What builders can experiment with today.

Creator Standards

Domain Chip Labs

Build domain chips, benchmark packs, specialization paths, autoloop policies, tool integrations, and publish packet drafts.

Character

Spark Character

Use the public identity, voice, permission, and character-evolution runtime.

Personality

Personality Chip Labs

Experiment with modular personality chips and profile composition.

Voice

Spark Voice Comms

Work with voice hooks, voice profiles, and local or paid provider examples.

Setup

Telegram and your LLM provider are the two keys.

Telegram is how you talk to Spark. The LLM provider is the model Spark uses to think and reply.

Create a Telegram bot Open Telegram, message @BotFather, and create a new bot. Keep the token private.
Find your Telegram ID After Spark starts, send /myid. Use that number as the admin ID.
Choose an LLM provider Choose one provider for Agent and Mission, or split them if you already know what you want.
Run the checks Use spark live start, spark providers test --role chat, and spark verify --onboarding.
Daily Use

The commands people actually need.

In Telegram

  • /start opens Spark.
  • /diagnose checks what is working.
  • /remember <note> saves a memory.
  • /recall <topic> searches memory.
  • /run <goal> starts a mission.
  • /board shows mission status.
  • /access 3 lets Spark research and build when you ask.

In Terminal

  • spark guide opens the walkthrough.
  • spark live start starts the background services.
  • spark live status checks those services.
  • spark providers status checks models.
  • spark providers test --role chat proves the chat model.
  • spark verify --onboarding checks setup.
  • spark security audit checks local launch safety.
Full command reference Provider setup Railway/VPS hosting Troubleshooting
Feedback

Send improvements to the right Spark repo.

If a doc, command, module, benchmark, or setup path can be better, route it as feedback or a PR. The feedback page helps humans and agents choose the repo, redact secrets, and write a useful issue.

Humans

Pick the area, then open GitHub.

Choose docs, CLI, Researcher, Telegram, Mission Control, memory, character, or chip work.

The page gives you a direct issue and PR path for each repo.

Agents

Prepare feedback safely.

Agents should name the repo, expected behavior, actual behavior, redacted evidence, and the smallest useful change.

Secrets, private memory, and raw logs stay out of GitHub.

Feedback guide Agent Markdown Open feedback
Self-Improvement

How Spark turns a task into a scored specialist.

A domain chip is both a tool Spark can use and a bounded specialization loop Spark Researcher can run.

It gives Spark a way to inspect one kind of work, score it, save the useful lesson, and suggest the next safe experiment. Feedback and PRs live in the feedback guide; this section is about benchmark-driven agent improvement.

Tool Score Memory Next Try
Domain Chips

The reusable specialist

A chip can focus on startups, trading, research, content, coding, diagnostics, or another repeatable task.

It owns evaluate, suggest, packets, and watchtower behavior for that domain.

Spark Researcher

The local lab

Researcher runs commands, bounded autoloops, memory sync, Obsidian notes, summaries, and reviewable ledgers.

Recursive Loops

The careful repeat

Recursive does not mean uncontrolled.

It means Spark repeats a bounded cycle: run, score, record, suggest, review.

Examples

What this looks like

Startup chips can score founder decisions. Trading chips can test strategies. Research chips can improve evidence quality.

The same loop can also improve prompts, workflows, and tools.

Ask your local agent like this

Use Spark Researcher's domain-chip authoring docs to design a Spark domain chip for <domain>.
Treat it as both a reusable tool my Spark agent can call and a bounded loop Spark Researcher can score.
Inspect ~/.spark/modules/spark-researcher/source/docs/master_chip_v2 before writing files.
Build the smallest v0 with evaluate, suggest, packets, watchtower, and tests.
Ask before making risky changes.
Self-improvement guide Feedback guide Spark suites
Fixes

When Spark is quiet, check these first.

Most quiet-bot problems come from one of three places: Telegram token, admin ID, or LLM provider setup.

Telegram gets commands, but replies are weird

Run spark providers status.

If the model role is missing, Spark may only show memory labels or empty status text.

Telegram gets nothing

Run spark fix telegram.

Then run spark logs spark-telegram-bot and look for token or polling errors.

Memory does not come back

Run spark verify --deep.

This checks memory, provider routing, and Mission Control wiring.

Mission Control is unreachable

Run spark fix spawner.

Then run spark live status and spark logs spawner-ui.

You want to stop Spark

Run spark autostart uninstall.

Use spark uninstall when you want to remove the local install.

For Agents

Give your coding agent a simple contract.

Agents should read the safety page, run a dry-run, explain the plan, and ask before doing a real install. 

Install Spark from https://agent.sparkswarm.ai/install.
Read https://agent.sparkswarm.ai/docs/install-safety.md first.
Download the installer. Do not pipe it into a shell.
Run the dry-run and explain the plan.
Ask me before any real install, token setup, autostart change, or uninstall.
AGENTS.md llms.txt llms-full.txt commands.json
Receipts

The safety proof is still here when you want it.

You do not need to understand every detail to use Spark. But the details are public so humans and agents can check the installer before trusting it.

What is verified

  • The installer scripts have published hashes.
  • The Spark CLI source is pinned to one commit.
  • Managed downloads are versioned and checked.
  • CI does dry-run and real-install smoke tests on macOS, Linux, and Windows.

Where to look