Collaborate: shared spaces

A space is a place shared with other people where you upload projects and files. Each item has its version history and its comments (on videos, at a specific second). Changes reach everyone who has the space open, live.

#Privacy: end-to-end encryption

When you create a space, Genesis generates a secret key that only travels in the invite link. Everything shared is encrypted on your computer with that key:

• the names of the files and of the space;
• the content;
• the members' names;
• the comments.

The encryption is XChaCha20-Poly1305 and each space has its own keys (HKDF-SHA256). The server only stores encrypted data under opaque names, plus the hash of the access token: it can't read or modify anything.

• Share the link over a private channel. Anyone who has it can join.
• If someone leaves the space, their downloaded copies stay on their computer.

#Ways to use it

#On the same network (no cloud)

Useful in an office or at home.

1. In Shared spaces, turn on Share on this network. This computer acts as the server on port 8787.
2. Create a space with the On this network option and send the link.
3. Anyone on the same network clicks the link: Genesis opens in Shared spaces with the invite filled in and only asks for their name. It can also be pasted into Join, for example if the link arrives on another device.

The computer acting as the server needs to be on for the others to sync. If the system asks, allow incoming connections for Genesis in the firewall.

#With your own server (from anywhere)

A single command, on any machine with Linux, macOS or Windows:

genesis share serve --port 8787 --data /var/lib/genesis-share --admin-token "a-long-key"

If you build genesis yourself, build the review page first (pnpm --filter @genesis/review build): it's embedded in the binary.

• --admin-token (or the GENESIS_SHARE_ADMIN_TOKEN variable) means only those who know it can create spaces. Joining one only requires its link.

• Put an HTTPS proxy in front. With Caddy this is enough:

  CodeCopy

  share.example.com {
      reverse_proxy 127.0.0.1:8787
  }

• As a systemd service:

  ConfigCopy

  [Unit]
  Description=Genesis share
  After=network.target
  
  [Service]
  ExecStart=/usr/local/bin/genesis share serve --host 127.0.0.1 --port 8787 --data /var/lib/genesis-share
  Environment=GENESIS_SHARE_ADMIN_TOKEN=a-long-key
  Restart=on-failure
  DynamicUser=yes
  StateDirectory=genesis-share
  
  [Install]
  WantedBy=multi-user.target

When creating the space in Genesis, choose On a server and enter https://share.example.com and the admin key.

#Edit together

Video edits, documents and spreadsheets in a space are edited live. Open them from Shared spaces and, if someone else has the same item open, you'll each see the other's changes instantly.

• Live appears at the top with the initials of who's in.
• You can see what each person is doing:
  • in documents, their cursor with their name;
  • in spreadsheets, the cell they're on;
  • in the video edit, the clip they have selected.
• Changes are merged. If each person touches different clips, cells or paragraphs, both are kept. If two people change the same value, the last one wins.
• Undo (Ctrl+Z) only undoes your own changes, never other people's.
• Offline you keep editing. When you're back, your changes are sent and you receive everyone else's.
• Media you add (a video, an image) is uploaded encrypted and appears for the others once it has finished downloading.
• Encryption: the server only relays and stores encrypted changes, in a room whose name doesn't reveal which item it is. Every so often it compacts them into a single encrypted state.
• To save a version in the history (so it can be approved from a phone), click Share as usual.

#Review from your phone or the browser

Nothing to install. The space's server also serves a review page:

1. In Shared spaces, click Link for phones and send it over a private channel. It looks like https://server/#espacio=…&k=….
2. When opened, it shows the space's items and their versions. From there you can:
   • play the preview;
   • comment at a specific second (tapping a comment's time jumps to that moment);
   • approve a version.
3. Everything reaches the desktop app instantly: the comments, and "Approved by …" in the version history.

End-to-end encrypted:

• The key goes after #, a part of the link the browser never sends to the server.
• The page decrypts on the phone itself (XChaCha20-Poly1305, same as the app) and removes the key from the address bar.
• The key is remembered on that device until you tap Forget this space on this device.

Light preview:

• When you share a video, Genesis also uploads a copy of up to 720p, encrypted like everything else, so the phone doesn't download the original.
• With audio it uploads an AAC copy, and with a photo, a JPEG.
• Genesis projects don't have a preview. For other files, the original can be downloaded.

Install as an app:

• With HTTPS (your own server with Caddy, or a tunnel), the page can be added to the home screen and opens like an app (Add to Home Screen on Android or iPhone).
• No app stores or developer accounts needed.

No public server: if you use Share on this network, the link works on a phone connected to the same Wi-Fi. To review from outside without paying for anything:

• Cloudflare Tunnel: cloudflared tunnel --url http://localhost:8787 gives you a temporary https://… address.
• Tailscale (tailscale funnel 8787).

In both cases, create the space with that https://… address as the server.

#What's shared and how

• Projects (.gvideo.json, .gdoc.json, .gslides.json, .gsheet.json, .gimg.json, .gaudio.json):
  • travel with all the videos, images and audio they use;
  • when downloaded, paths point to the downloaded copies, so they open as they are.
• Any other file (video, PDF, Word…) is shared as is.
• Versions:
  • sharing again a file that came from the space (or that you already shared) creates a new version of the same item;
  • the others see a New version notice;
  • previous versions can be opened from the history.
• Efficiency: files travel in 8 MiB chunks, and a chunk already on the server isn't uploaded again. Changing the title of a 2 GB video edit uploads a few KB.
• Comments: on videos and audio you can give the second (01:23); clicking it opens the editor at that point.
• Downloads are saved in Documents/Genesis/Espacios/<space>/.

#From the CLI and via MCP

Everything is available as share.* tools:

Example:

genesis run share.push space=<id> path=~/Projects/Ad.gvideo.json note="Trimmed the intro"

An AI connected via MCP can, for example, «upload the edit to the team space and say in a comment what changed».

#Limits

• The image and audio editors work by versions: each person works on their copy and shares it. If two people share at the same time, both versions stay in the history and nothing is lost.
• The server accepts files up to 8 GB (already encrypted).
• Where space keys are stored:
  • In the system keychain (macOS Keychain, Windows Credential Manager or Secret Service on Linux). Keys from earlier versions are moved there automatically.
  • On computers without a keychain (a Linux without a desktop, the CLI on a server), they're stored in a file readable only by your user. Shared spaces says so.
  • If the keychain loses a key, open the invite link again and it's recovered.