First run on your own machine

What `spl init` creates on a local install, how to inspect your identity and config, and when to re-initialize. Once the workspace is up, Your first hour describes what it does next.

This page is for people running their own workspace or using the API. If you use a workspace created at syncropel.com, start with Your hosted workspace.

First run on Linux/macOS is three short verbs

spl init --preset recommended   # generate identity + config, install the assistant
spl serve          # start the workspace in the background
spl task add "..." # everything works immediately: no service account, no bearer

Once it is up, read Your first hour: a fresh workspace set up with a preset asks you one question, and answering it opens your first thread.

The local CLI talks to the workspace over a Unix socket at ~/.syncro/run/spl.sock; filesystem permissions (the socket is mode 0700 owned by your user) are the authentication. Bearer tokens are still the right primitive for delegating scoped access: see Service accounts and tokens when you need to pair a browser, phone, MCP client, remote CLI, or another workspace.

spl serve / spl stop / spl restart are the convenience verbs for interactive use; the full spl serve form (foreground) is the canonical entry point used by systemd units, Docker containers, Kubernetes pods, managed cloud platforms, and other process supervisors.

After spl version prints cleanly, run spl init once to create your local state directory.

`spl init`

spl init --preset recommended

This creates ~/.syncro/ with default contents and a fresh identity, and applies the recommended preset: the assistant is installed, and one question ("What are you working on?") is placed in your call, waiting for you when the workspace starts. Pass --preset blank for a workspace with nothing installed and no question. A bare spl init with no --preset applies none: the workspace starts unconfigured, with no assistant and no question, until a preset is applied (the Studio's first-run card offers them). An unknown preset name is refused before anything is written.

The new directory tree:

~/.syncro/
├── config.toml              Identity, default model, server settings
├── token                    Bearer token for the CLI (created later; see Service accounts and tokens)
├── keys/                    Signing keys for your identity
│   ├── primary.pub                    Public key
│   └── did_sync_user_<name>.priv     Private key (mode 0600), named after your `actor` value
├── logs/                    Workspace logs (populated on first start)
├── run/                     PID file + Unix socket (populated on first start)
├── secrets/                 API keys for upstream providers (empty until you add)
└── hub.db                   Main record store (created at init; grows from first start)

On Windows, the same tree lives under %USERPROFILE%\.syncro\.

Your identity

spl init generates a did:key-format identity and writes it into config.toml:

[identity]
actor = "did:sync:user:you"
did = "did:key:z6Mk..."
method = "key"
key_path = "/home/you/.syncro/keys/primary"

actor is the human-readable name you'll see attached to every record you emit. It defaults to did:sync:user:<your-username>, the same username your OS reports.
did is the cryptographic identity. A fresh keypair is generated and the public half becomes the did:key: string. The private half is stored under ~/.syncro/keys/ (named after your actor value) with mode 0600.
method names the identity method (key on a fresh install; web or sync after an upgrade).
key_path points at the keypair the workspace signs with.

Inspect the result:

spl identity show

Expected output:

Identity:
  DID:         did:key:z6Mk...
  Method:      key
  Key path:    /home/you/.syncro/keys/primary
  Actor:       did:sync:user:you

Inspecting `config.toml`

cat ~/.syncro/config.toml

The default file is small, tens of lines. The blocks you'll see:

[identity]: the identity and keypair above.
[server]: bind address (127.0.0.1), port (9100), data dir, backup dir.
[intelligence]: which language model your workspace uses, and your own provider key. On a local workspace you will need this; see the note below.
[fleet]: advertised endpoint for fleet mode (not relevant for single-machine use).

A local workspace has no model until you give it a key

A hosted workspace arrives with managed model access (free plans include a one-time inference allowance). A workspace on your own machine does not: the assistant is installed by the preset but has nothing to answer with until you supply a provider key. Run spl config set-key anthropic <your key>, then spl stop and spl serve --daemon. Until then the assistant is silent, and spl run says so rather than failing quietly.

The assistant and the first question (self-host)

Every preset except blank installs the chief of staff (the chief), the member that answers when you type in a thread, and seeds the one question a fresh workspace asks: "What are you working on?" Answering it opens your first thread, titled by your words. Your first hour walks through it.

A blank workspace starts deliberately empty: nothing answers and nothing is asked until you choose what runs on it. To add the assistant later:

spl blueprint plan <blueprint.json>                        # review what it installs, get the plan hash
spl blueprint install <blueprint.json> --accept-plan <hash> # any time, on an already-initialized workspace

The source repository ships the chief-of-staff blueprint together with an install script that signs, plans and installs it; see Blueprints for the verbs.

Installing the chief later does not add the question; it only ever seeds when the workspace is first configured with a preset. On a blank workspace, open your first thread yourself. If you initialized blank and the assistant seems silent, this is why, and nothing is broken.

Workspaces before v0.216 had a separate built-in assistant, configured with spl config scribe. That verb is gone: the conversational default is now an ordinary member, defined by a blueprint like any other, so what answers you is something you can read, change and replace. Old configuration records are still readable as history.

(Hosted workspaces come with the assistant already on.)

Editing config.toml by hand is supported. Changes take effect on the next start. For runtime config (routing rules, permissions, embedding providers), use spl config … commands instead: those changes hot-reload without a restart.

When to re-initialize

Almost never. spl init is a one-time operation; running it again against an existing ~/.syncro/ is a no-op unless you pass --force:

spl init --force

--force overwrites config.toml and regenerates the keypair. The existing hub.db is left alone: your records survive. But the new keypair will sign records under the same actor value as before, which means verification of old records against the new public key will fail. For practical purposes, --force is only appropriate on a machine that has never been used for real work.

If you want a fully clean state (new identity and new data), see Reset and uninstall.

Identity types

This machine's own identity (the default)

What spl init creates: an identity whose private key lives on this one machine. If you set up another machine the same way, it gets its own, separate identity. This is the right default for a single-machine installation.

Note this is different from signing in on the web or to a hosted workspace: there, your content is owned by your sign-in identity, which is the same on every device. See Your identity & recovery for how that works.

One identity across your machines

For machines you maintain yourself, master identity mode gives every device the same root identity: each machine's key is derived from one root you hold, and a 24-word recovery phrase can rebuild it anywhere. Start a fresh install with:

spl init --master

Master mode is an init-time decision: there is no migration from a per-machine identity to master mode later. (spl identity upgrade does something different: it moves an existing identity to a more capable identity method, key to web or sync, and the identity itself stays the same.) Either way, portability is optional: you can run Syncropel for years on a single machine without it.

Permissions

After spl init:

ls -la ~/.syncro/ ~/.syncro/keys/

Verify:

~/.syncro/config.toml is never world-writable.
The private key under ~/.syncro/keys/ is mode 0600.
~/.syncro/token (once created) is mode 0600.

The directory itself is created with your OS's default permissions; the secrets inside it (keys, tokens) carry their own 0600. If anything looks off, spl doctor will flag it with the exact chmod fix.