Quickstart

What you'll have at the end

A running Syncropel instance on your machine, your first task tracked through completion and approval, and a trust score that proves the loop works. From there you can dispatch work to AI agents, write CEL rules to automate decisions, or invite collaborators — all on the same record log you just started.

This page is for humans who want to use Syncropel directly. If you're integrating an AI agent, see Agent Integration instead.

Time: 10 minutes. Prerequisites: Linux (x86_64 or aarch64) or Windows. No Rust toolchain, no Docker, no API key required for this walkthrough. macOS users need to build from source today — a prebuilt binary is coming.

1. Install

Linux

curl -sSf https://get.syncropic.com/spl | sh

Windows (PowerShell)

irm https://get.syncropic.com/spl.ps1 | iex

Both scripts download the right binary for your platform from releases.syncropic.com, place it in ~/.local/bin/spl (Linux) or %LOCALAPPDATA%\Programs\spl\spl.exe (Windows), and verify the version. If the install location isn't already on your PATH, the script will tell you what to add to your shell or environment.

Verify it landed:

spl version

You should see spl <version> printed (e.g. spl 0.X.Y). If not, check the install script's output for errors — it's verbose by design.

2. Initialize your environment

spl init

This creates ~/.syncro/ with sane defaults:

• ~/.syncro/config.toml — your identity, default model, server settings
• ~/.syncro/run/ — runtime files (PID file, Unix socket)
• ~/.syncro/logs/ — instance logs
• ~/.syncro/secrets/ — empty, ready for API keys later

The default identity is did:sync:user:<your-username>. You can edit config.toml to change it.

spl init ends with the next steps you'll actually need:

Next steps:
  1. Start your instance:    spl serve --daemon
  2. Add your first task:    spl task add "finish report"
  3. View tasks in browser:  https://syncropel.com/local

3. Start your instance

spl serve --daemon

--daemon puts the kernel in the background. It opens ~/.syncro/hub.db (creating it on first run), takes a startup backup, binds 127.0.0.1:9100, and starts the four loops (ingest, reconcile, tick, cron). The post-start banner tells you where to go:

Starting spl serve (PID 12345)... ready.
  API:   http://127.0.0.1:9100
  Web:   https://syncropel.com/local
  Logs:  ~/.syncro/logs/spl.log
  Stop:  spl serve --stop

Verify it's healthy:

spl status

Expected output:

Syncropel kernel <version>
Status:  ok
PID:     12345
Uptime:  3s
Store:   sqlite:///home/you/.syncro/hub.db (1 records, 1 threads)

The "1 records, 1 threads" is the instance's bootstrap LEARN record on th_engine_config — that's the engine writing its own initial config as a record. Everything in Syncropel is records, including the kernel's own state.

4. Create your first task

Tasks in Syncropel aren't just todos — they're threads with hypotheses, success criteria, and trust attribution. Create one:

spl task add "Read the Syncropel quickstart" \
  --priority high \
  --domain learning

The CLI assigns it an alias like TASK-0001 and prints the task ID. List your tasks:

spl task list

You'll see one row with status inbox (no work done yet).

Show the full detail:

spl task show TASK-0001

5. Work the task and complete it

Mark the task as active (you're working on it):

spl task start TASK-0001

Status flips to active. The CLI emits a DO record on the task's thread.

When you're done — for this walkthrough, that's "you finished reading the quickstart" — mark it complete:

spl task done TASK-0001 \
  --summary "Read it. Set up local kernel. Created my first task and completed it." \
  --domain learning

Status flips to review (waiting for evaluation).

6. Approve the completion (and earn your first trust)

Tasks need an evaluator distinct from the executor. For solo use, you can act as both:

spl task approve TASK-0001 --notes "Quickstart goal achieved"

If approve complains about self-evaluation, set a different actor for the approval:

SPL_ACTOR=did:sync:user:<your-username>-reviewer spl task approve TASK-0001 \
  --notes "Quickstart goal achieved"

The status now flips to approved (terminal). And — because you completed and got approved in the learning domain — your trust score has its first data point:

spl trust

You should see a row with your DID, domain learning, and a small but non-zero Wilson lower bound. That's the loop: produce a record, get evaluated, accumulate evidence, derive trust. Every other Syncropel feature builds on this primitive.

7. Look at the records you just created

Tasks are threads. The thread for TASK-0001 contains every record you generated during the last few minutes. Show them:

spl thread show TASK-0001
spl thread records TASK-0001

You should see roughly:

Four records. Immutable. Content-addressed. Each one has a SHA-256 ID derived from its 7 hashed fields. Every spl command from here on either reads existing records or writes new ones to a thread.

8. What to do next

You now have a working kernel, a completed task, a trust score, and an understanding of how records, threads, and verdicts compose. From here:

• Tutorials — guided walkthroughs of the next 30 minutes (first task, first thread, first workspace, first SDK integration).
• Concepts — read why records are 8 fields, how the dial scales from REPLAY to CREATE, what trust is.
• Guides — task-oriented how-tos for common operations (CEL expressions, routing, agent integration, Docker deployment).
• Keeping your instance running — auto-start at login + auto-restart on crash. systemd user unit on Linux, launchd plist on macOS, Windows Service on Windows.
• Operator Runbook — when you're ready to keep this instance running for real work, this page covers backup discipline, recovery, and upgrades.

Common pitfalls

spl serve --daemon says it started but spl status says no instance. The instance may have failed to bind the port. Check ~/.syncro/logs/spl.log for the error. Most common cause: another process is on localhost:9100 (a previous instance, or another tool).

spl task done complains about uncommitted changes. The task completion gate refuses to mark a task complete when the working tree has uncommitted git changes — it's protecting against attributing wrong commits. Either commit your work first (you don't need to push), or pass --force if the change is unrelated to the task.

spl task approve refuses self-evaluation. Single-actor approval is gated by design — multi-user governance assumes the evaluator is someone other than the executor. The workaround for solo use is the SPL_ACTOR=... env var trick shown above. A future release will add a single-user mode flag.

The CLI hangs on spl serve --stop. The instance may have lost its PID file. Use pgrep -af "spl serve" to find the process, then kill <pid>. See the Operator Runbook for the detail.

macOS

A prebuilt macOS binary is on the near-term roadmap. Until then, macOS users have three working paths:

• Run spl inside a Linux VM or Docker container and expose port 9100 to the Mac.
• Run spl serve on a remote Linux host and pair the local browser to it (see Pairing).
• Use WSL on a Windows machine.

See the install page for the detailed alternatives.

Build time is ~5-10 minutes on a modern Mac. Subsequent rebuilds are seconds via cargo's incremental compilation. If Rust isn't your thing, you can also run spl in Docker — see the Docker deployment guide.