First Run — init, identity, keys

What `spl init` creates, how to inspect your identity and config, and when to re-initialize. Covers the `~/.syncro/` directory tree and how identities work.

First run on Linux/macOS is three short verbs

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

The local CLI talks to the instance 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 instance.

spl serve / spl stop / spl restart are the convenience verbs for interactive operator 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

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
│   ├── default.priv         Private key (mode 0600)
│   └── default.pub          Public key
├── logs/                    Instance logs (created on first instance start)
├── run/                     PID file + Unix socket (created on first instance start)
├── secrets/                 API keys for upstream providers (empty until you add)
└── hub.db                   Main record store (created on first instance 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_key = "did:key:z6Mk..."

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_key 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 at ~/.syncro/keys/default.priv with mode 0600.

Inspect the result:

spl identity show

Expected output:

Actor:      did:sync:user:you
DID (key):  did:key:z6Mk...
Public key: ~/.syncro/keys/default.pub
Private key: ~/.syncro/keys/default.priv (0600)

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).

Your instance can already use a model out of the box

A fresh instance ships with managed model access built in. The conversational agent and work loops work immediately after spl init — you do not have to configure a provider or supply an API key just to get the assistant responding.

Setting a provider key in [intelligence] is an optional override, for when you want to use your own account or a specific model instead of the built-in managed access. Until you do, your instance uses the managed model access automatically.

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.

spl init --master

There is also spl identity upgrade for migrating an existing identity to a portable format. Either way, portability is optional — you can run Syncropel for years on a single machine without it.

Permissions

After spl init:

ls -la ~/.syncro/

Verify:

~/.syncro/ is mode 0700 (only you can read it).
~/.syncro/config.toml is mode 0600 or 0644 (never world-writable).
~/.syncro/keys/default.priv is mode 0600.
~/.syncro/token (once created) is mode 0600.

If any of these look off, spl doctor will flag them with the exact chmod fix.

First Run — init, identity, keys

`spl init`

Your identity

Inspecting `config.toml`

When to re-initialize

Identity types

This machine's own identity (the default)

One identity across your machines

Permissions

See also

On this page