Getting Started

1. Install kutl

brew install kutl-io/tap/kutl

The source option requires a Rust toolchain. kutl-relay is included in the same package.

2. Start a relay

The relay is the server that coordinates sync between participants. For local development, start it with no flags — it binds to loopback only and accepts unauthenticated connections from clients on the same machine:

kutl-relay

The relay listens on ws://127.0.0.1:9100/ws by default — also the default URL that kutl init and kutl join connect to, so no --relay flag is needed during development. See Self-Hosting a Relay for network-reachable and production deployment.

Prefer Docker? A multi-arch image is published at ghcr.io/kutl-io/kutl-relay:

docker run --rm -p 9100:9100 \
  -e KUTL_RELAY_ALLOW_OPEN_RELAY=true \
  ghcr.io/kutl-io/kutl-relay

See Running in Docker for compose files, persistent volumes, and network-reachable deployment.

3. Initialize a space

A space is a named sync context: a directory whose contents sync with the relay. Create one inside your project:

cd /path/to/your/project
kutl init --name my-project

This creates a .kutlspace file (team config, safe to commit) and a .kutl/ directory (local state, gitignored). If you're inside a git repo, kutl creates a subfolder to keep synced documents separate from your code.

The --name flag registers a human-readable name with the relay. Other users will use this name to join. If you omit it, a name is generated automatically.

4. Start the daemon

The daemon watches your files and syncs changes with the relay in the background:

kutl daemon start

You can also run it in the foreground with kutl daemon run to see logs directly. Check status with kutl status.

5. Join from another machine

On a second machine (or in a second directory), join the space by name:

kutl join my-project --relay ws://<relay-host>:9100/ws
kutl daemon start

If the relay is running on localhost, you can omit the --relay flag since it defaults to ws://127.0.0.1:9100/ws.

6. Edit and sync

Create or edit files inside the space directory. Changes sync automatically through the daemon. Any editor, script, or agent that reads and writes files becomes a sync participant. No commits, no pushes, no manual merges.

One-shot sync

If you don't want a background daemon, you can sync once and exit:

kutl sync

This pushes local changes, pulls remote changes, and exits. Useful for CI pipelines or scripts.