Skip to main content



WARNING: this document is old and outdated#


URL details#

The workspace and author address formats are designed to work well in URLs with two caveats:

  • Sometimes the sigils need to be removed (+ from workspace, @ from author)
  • base58 is case sensitive, but URL locations are supposed to be lowercase (at least for HTTP)

These rules make them URL-safe:

  • Paths are already required to use percent-encoding for weird characters, so they work in URLs without change
  • Workspaces and authors only contain alphanumeric chars, ., +, and @
  • Workspace and authors have a dot in the middle so they're recognized as domains by browsers
  • Workspace and author parts can't start with a number (including the base58 keys)
  • Paths can't start with /@. This avoids ambiguity between WORKSPACE/PATH and WORKSPACE/AUTHOR

So except for the base58 case issue, these are all guaranteed to be valid URLs.


examples, using xxxxx to stand in for long base58 strings


The author:password@workspace format puts the @ in a confusing place compared with normal Earthstar sigils. It could be OK just for doing writes in the fetch API if end users never see it in the browser UI?

Pubs & swarms#

These URLs don't contain pub information, except maybe one pub in the case of the http:// URLs. But there could be multiple pubs and multiple swarms.

There will be 2 kinds of swarms:

  • the usual main swarm: swarm key = hash(workspaceAddress), like DAT
  • secret swarms: swarmKey = hash(workspaceAddress + swarmPassword)

Swarm passwords are just secret strings you share with friends. They let you connect only to trusted peers when you're in a very large or public workspace to protect your IP address privacy.