Edit the same file together, on a server you run.

Get it working

One server holds the room, and the editor you already use is where you type. Run the published container, then open one row per editor below.

Start a server

docker run --rm -p 127.0.0.1:8080:8080 ghcr.io/selvage-protocol/selvaged:0.2.0

The server answers ws://127.0.0.1:8080/session and reports on http://127.0.0.1:8080/meta, one port for the room and the page that joins it. Rooms live in memory, so a restart ends them. The 127.0.0.1 binding keeps the room on your own machine; serving guests on other machines means rebinding (for example -p 8080:8080) and an invite URL that names a reachable address. selvage-protocol/reference_server holds the compose file and the source build.

The server relays ciphertext, and cannot tell who is host. Documents, cursors, the file listing, which files are open and who may edit are sealed under keys that travel in the part of the link a browser never sends to a server, and the decisions a session used to ask the server to make are signed by the peers instead. The box — and whoever holds it — carries bytes it cannot read. It still sees that a room exists, who is in it, their names, and the sizes and timing of what moves.

Pick your editor

One row per editor, folded shut. The commands inside are the ones the editor's own README documents.

git clone https://github.com/selvage-protocol/vscode_client
cd vscode_client
npm ci --no-audit --no-fund
npm run package
code --install-extension selvage-client-<version>.vsix

{ 'selvage-protocol/nvim_client', build = 'npm ci' }

http://127.0.0.1:8080/?room=<room>&token=<token>

Try the demo

A small instance of the server runs at selvage-demo.dontblameme.dev. Point one of the editors above at wss://selvage-demo.dontblameme.dev and it hosts a room there: selvage.serverUrl in VS Code, vim.g.selvage_server_url in Neovim. A host started with neither setting asks for the address. The invite link it copies opens the room in the browser page, so a guest needs nothing installed. Chrome or Edge can start a room there from the page itself, with no editor running at all.

Rooms live in memory on one small box, and a restart ends every one of them. Run the server above for work you need to keep, on your own machine or on one you rent. The instance is for personal and evaluation use, and non-commercial: its terms cover this one box, and the licences below decide what the software itself may be used for, selvaged's FSL-1.1-MIT reserving commercial hosting for the project.

See it working

A room is the host's folder, seen from somebody else's editor.

• invite link?room=k7m2&token=4f9c…

  Anyone with the link is in

  Hold the link and you are in. There is no approval step, and nobody waits for the host to let them in. Treat an invite the way you would treat a password.

• 1/// Publish this peer's caret.2async fn caret(3    engine: &SyncEngine,mira4    path: &str,jonas5    at: SelectionOffsets,6) -> Result<(), Error> {7    engine.set_selection(path, at)8        .await9}

  Two carets, one text

  Everyone's edits land in the one CRDT, and carets and selections travel as anchors inside it. A peer's caret stays where it was while the text around it moves.

• guest · mirror

  • src/
  • main.rs
  • room.rs
  • session.rs

  A guest sees the paths you granted

  The host publishes the paths inside the folder it granted, and reads a file from its own disk when somebody opens it. The room never adds, renames or removes a path in your working copy.

• VS Code Neovim a browser page

  one engine · selvage/1

  Multiple clients, one engine

  The VS Code client, the Neovim client and the browser page each drive a copy of the same engine and bridge, so a room's rules live in one implementation. The page joins a room from a link, and on the server's own page, Chrome or Edge can start one from a folder you pick.

How it works

The workflow is one sentence: share a link, come edit my code with me. In order, it comes to four moves.

1. Host a folder. Start the server, open a folder in VS Code or Neovim, and host a session from the command palette. On the server's own page, Chrome or Edge can host from a folder the page asks for. The host lists the paths inside that folder and sends the listing.
2. Send the invite. Copy the invite link and send it however you already talk to each other. The token in it is the permission, and only the paths you granted are behind it. The host's client holds that confinement; nothing on the wire enforces it.
3. Type in the same file. A guest opens a file when they want it, and the host reads it from disk at that moment. A file nobody has opened sends no text, so opening one file never moves the whole project over the wire.
4. Close the window. The room dies with its host after a short grace period, so a dropped connection does not end it. Rooms live in memory: nothing survives a restart of the server.

The session layer has no specification

Language tooling has the Language Server Protocol and debugging has the Debug Adapter Protocol. Document sync has y-protocols and the CRDT libraries beneath it. Which rooms exist, who is in one, what their role is, which documents are open, where their carets are, what happens when somebody leaves: every collaborative tool decides those for itself, so none of the tools can talk to each other.

The specification is Selvage's flagship artifact: that layer, written out as prose, a canonical byte form for a frame, JSON Schema documents, and 31 conformance vectors (34858 frame checks and 8642 assertions) replayed byte for byte against a real server. The numbers are constants in schema/validate.py, so deleting an assertion fails the run instead of shrinking a total in a line of output.

The vectors are also the honest test: nothing yet shows that code written from the prose alone agrees with this implementation byte for byte, and a corpus you can replay is what would settle it.

Read the specification. It is written to be implemented on its own, without reading the Rust.

git clone https://github.com/selvage-protocol/specification
cd specification
pip install jsonschema referencing
python3 schema/validate.py

git clone https://github.com/selvage-protocol/reference_server
git clone https://github.com/selvage-protocol/specification
cd reference_server
nix develop . -c cargo build -p selvaged
export SELVAGE_SELVAGED=$PWD/target/debug/selvaged
cd ../specification
pip install websockets jsonschema referencing
python3 runner/run_vectors.py