Start System One locally.

Launch System One

npx sysone

The command downloads a verified application runtime, starts its local engine and opens Studio. No source checkout or separate server setup is needed. Requires Node 22.18+ and internet access for the first download.

1. Open Settings and add your Vercel AI Gateway key.
2. Open Library, choose Check a claim and edit its example evidence. The claim-checking guide explains the input and result.
3. Run it and inspect the result in the decision control center.
4. Use Connections to create a scoped key for your agent.

Keep the terminal running. Ctrl+C stops the engine. A second launch opens a matching running instance. For a server-only session use npx sysone app --no-open; an isolated instance can use --port 4320 --home /private/path.

The launcher, SDK, MCP bridge and skill are open source. The compiled application runtime has a separate preview license and its source stays private. The runtime is cached under ~/.cache/systemoneengine; private settings stay under ~/.config/systemoneengine.

Use a scoped connection

In the Connections section of Studio, create a consumer credential with the services, expiration and daily request/model-call limits your agent needs. Save the connection JSON in a private file.

Keep the consumer token in a server environment or a private connection file. A provider key or administrator token is never needed by the client.

// /private/path/agent.json
{
  "url": "http://127.0.0.1:4319",
  "token": "YOUR_SCOPED_CONSUMER_TOKEN"
}

Local engines use loopback HTTP. Hosted engines use HTTPS. Check the connection without making a model call:

npx sysone status --connection /private/path/agent.json

Alternatively, set SYSONE_URL and SYSONE_TOKEN in the client process environment. Do not paste credentials into a chat or source repository.

Run a recipe

import { createClient } from 'sysone/client';

const engine = createClient({
  url: process.env.SYSONE_URL,
  token: process.env.SYSONE_TOKEN,
});

const result = await engine.runPattern({
  pattern: 'palette-match',
  state: 'A calm dark workspace with one restrained accent.',
  candidates: {
    slate: 'Dark slate, pale text, restrained blue accent',
    festival: 'Bright yellow, magenta and saturated orange',
  },
});

engine.capabilities() returns the connection's scopes and limits without inference. engine.patterns() returns the recipes available to the connection. Install the SDK with npm install sysone. The four services are decide, logs, tree and dialogue.

Call POST /v1/patterns/run with the same recipe input. Selection recipes require your own candidate IDs and descriptions. The engine adds a review option when none fits. Custom questions can use engine.run('decide', input). You can also call POST /v1/:service directly using a consumer bearer token. The public package exports request schemas; Studio lets you inspect and try each contract.

Give an agent the MCP tools

Configure a local MCP client to launch npx with the following arguments:

["-y", "sysone", "mcp", "--connection", "/private/path/agent.json"]

The bridge exposes sysone_status, sysone_patterns, sysone_run, sysone_decide, sysone_logs, sysone_tree and sysone_dialogue. The credential determines which services it can use. Use sysone_patterns({query: "palette"}) to find a recipe. Then call sysone_run with its ID, your current evidence and any required candidates. The agent does not need to write question prompts. Fetch a recipe by id to inspect its questions, policy and evidence before using it.

The package's skills/sysone folder contains the agent skill. Add it to the skill directory your agent supports so the reasoning model knows when to offload a question and how to handle uncertainty.

Engines also expose Streamable HTTP MCP at /mcp, with a consumer bearer token or owner-approved OAuth. OAuth uses PKCE, explicit consent, scoped connections and rotating credentials.

Measure what offloading changes

Offloading adds a request. It helps when the saved reasoning work outweighs that extra cost and latency. Test representative tasks before making it your default.

• Compare task quality and final outcomes with and without System One.
• Measure end-to-end latency, including escalations and timeouts.
• Count attempts and tokens across both the fast model and reasoning model.
• Separate cache hits from fresh model evaluations.
• Use actual provider pricing. Usage receipts are not a billing invoice.

Use the workflow measurement guide to record the full comparison. Failed model attempts remain counted. The engine never automatically calls a more expensive model.