First Run — init, identity, keys

spl init           # generate identity + config
spl serve          # start the instance in the background
spl task add "..." # everything works immediately — no service account, no bearer

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

spl init

spl init

This creates ~/.syncro/ with default contents and a fresh identity.

The new directory tree:

~/.syncro/
├── config.toml              Identity, default model, server settings
├── token                    Bearer token for the CLI (created later; see page 4)
├── keys/                    Ed25519 signing keys for your identity
│   ├── primary.pub                    Public key
│   └── did_sync_user_<name>.priv     Private key (mode 0600), named after your actor DID
├── logs/                    Instance logs (populated on first instance start)
├── run/                     PID file + Unix socket (populated on first instance 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 DID 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 Ed25519 keypair is generated and the public half is encoded into a did:key: string. The private half is stored under ~/.syncro/keys/ (named after your actor DID) with mode 0600.
• method names the DID method (key on a fresh install; web or sync after an upgrade).
• key_path points at the keypair the instance 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 DID + keypair above.
• [server] — bind address (127.0.0.1), port (9100), data dir, backup dir.
• [intelligence] — an optional override for which language model your instance uses (and your own provider key, if you bring one). You usually do not need to touch this — see the note below.
• [fleet] — advertised endpoint for fleet mode (not relevant for single-machine use).

Turning the assistant on (self-host)

A self-hosted instance starts deliberately blank: it reacts to nothing until you choose what runs on it. Two ways to give it a voice:

spl init --preset personal     # at init: seed a ready-to-use setup
                               # (presets: personal · team · research · builder · blank)

spl config scribe enable       # any time later: enable the conversational
                               # agent on an already-initialized instance

spl config scribe enable shows a short privacy disclosure and turns the assistant on for new conversations; spl config scribe status shows what's configured, and disable turns it back off. If you initialized bare and the assistant seems silent, this is why — nothing is broken.

(Hosted instances come with the assistant already on.)

Editing config.toml by hand is supported. Changes take effect on the next instance start. For runtime config (routing rules, fold 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 DID 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 instance: 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 DID method — key → web or sync — 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.

See also

• Pairing a browser or phone — get a second device onto the same instance
• spl doctor — audit your ~/.syncro/ state at any time
• Quickstart — five-minute happy path if you haven't done it yet