Quickstart

Install one CLI package globally, start the local server and enter the terminal TUI with a single command, then declare a model provider once. Every command, port and file path below maps to the repository source.

Prerequisites

Spark runs on Node.js. Make sure Node.js 24 or newer is installed, plus npm or pnpm. Verify with:

bash

node --version   # needs >= 24

Install

@spark/cli's npm release has not landed yet (v1.0.0 is tagged; the publish step waits on CI credentials), so run from source for now. Install dependencies once, build one server bundle — theupafterwards and the globally installedspark upshare the same code path:

bash

git clone https://github.com/Wanfeng1028/Spark && cd Spark
pnpm install                    # Node >= 24, pnpm 9
pnpm --filter @spark/cli build  # esbuild single-file bundle for the server

Once published, this section becomesnpm i -g @spark/cli (with pnpm:pnpm add -g @spark/cli).

Start

Enter your target project directory and runspark upto start the local Agent workbench:

bash

cd your-project
node <path-to-Spark>/apps/cli/dist/main.js up   # from source; becomes spark up after the npm release

The server binds to127.0.0.1:4318(the port comes fromSPARK_PORT, otherwise from~/.spark/spark.jsoninserver.port) — reachable from this machine only.

spark uppolls/api/healthzuntil ready, then hands the terminal to the Ink TUI — it never opens a browser for you. For the Web workbench, visit the same address yourself — the server statically servesapps/web/distwith unknown routes falling back to index.html. Exiting the TUI tears down the server child process it started — nothing left behind.

If a server is already running,spark updetects and reuses it instead of starting a second one; point at a custom base URL withspark up --api <url>or the environment variableSPARK_API。

Configure a model

The engine ships a catalog of 8 providers (openai / anthropic / deepseek / openrouter / groq / together / xai / mistral); baseUrl can point at any OpenAI-compatible endpoint. Declare it once in~/.spark/models.jsonbefore the first turn — defaultModel is required:

~/.spark/models.json

{
  "providers": {
    "deepseek": {
      "apiKeyEnv": "DEEPSEEK_API_KEY",
      "baseUrl": "https://api.deepseek.com/v1"
    }
  },
  "defaultModel": {
    "provider": "deepseek",
    "model": "deepseek-chat",
    "contextWindow": 128000
  }
}

API keys are read from environment variables only — never persisted, never logged:

bash

export DEEPSEEK_API_KEY=sk-...

Three config files live under~/.spark/:spark.json(server binding and engine behavior, optional),models.json(providers and model routing, required),permissions.json(approval rules; empty by default = everything falls back to ask). Loading runs zod validation — a failure raisesE_CONFIGand startup aborts. No running in a broken state.

Start chatting

Type natural language in the TUI to begin; the Web workbench lives athttp://127.0.0.1:4318. Every tool call's input, output and duration stream onto the screen as events; write-class tools and bash raise an approval card (1 allow once / 2 always allow / 4 always for this project / 3 reject with advice) — an unanswered ask settles to reject.

Quickstart

Prerequisites

Install

Start

Configure a model

Start chatting

Next steps