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.

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] — which LLM provider is default (anthropic, openai, ollama), and the default model.
[fleet] — advertised endpoint for fleet mode (not relevant for single-machine use).

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

Ephemeral `did:key` (the default)

What spl init creates. The private key lives on this one machine. If you move to another machine, that machine gets its own identity and your records won't be attributable to a single person across both hosts. This is the right default for a single-machine installation and for most users.

Portable identities

For users who want a single DID across multiple devices, spl identity upgrade migrates the ephemeral did:key to a portable format backed by a shared signing key. The upgrade path and supported formats are covered in Actor portability.

Portability is optional. You can run Syncropel for years without upgrading.

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.