This user interface lets you interact with Radicle, a peer-to-peer code collaboration and publishing stack, directly from your web browser.
Deployment Options:
- Public Server: The Radicle team maintains a public instance at radicle.network
- Local-first: Run the UI locally
- Self-hosting: Deploy the UI on your own server
Prerequisites:
Run the following commands to access the web UI locally:
git clone https://seed.radicle.dev/z4V1sjrXqjvFdnCUbxPFqd5p4DtH5.git radicle-explorer
cd radicle-explorer
npm install
npm startThen open http://localhost:3000 in your favourite browser.
There are several ways to deploy the UI publicly. Here are two common options:
Using your own web server:
- Run
npm install && npm buildto create a build for deployment - Configure your web server to serve the contents of the
/builddirectory
Using Vercel (or similar static file hosting):
- Fork this repository to create your own version
- Configure your Vercel account to deploy the forked repository
Add Rewrite Rules for Client-Side Routing
The explorer is a single-page application (SPA). To ensure that all routes are handled correctly, add a rewrite rule to your web server configuration. For example:
Caddy:
example.com {
rewrite * /index.html
}
There are two ways to configure the UI: at build time and at run time.
This method is recommended when deploying to static hosting platforms such as Vercel.
- Copy
default.jsonto a new file in the same directory calledlocal.json. - Modify the properties in
local.jsonto suit your setup.
- Refer to
custom-environment-variables.jsonfor a list of supported environment variables. - Set the desired variables in your environment before building the UI.
For advanced configuration options, refer to the
node-configdocumentation.
This method is useful when the app is distributed as a precompiled static JS/HTML bundle, such as when installed via a package manager.
You can build the app in a mode that loads configuration dynamically from the server it's deployed to, instead of bundling it at build time.
To enable this behavior, set the environment variable VITE_RUNTIME_CONFIG=true
during the build:
VITE_RUNTIME_CONFIG=true npm run buildThis will inject a blocking script into the index.html that attempts to load
the configuration from a pre-defined location (/config.json) on the server.
The config file must be served as static content and must be publicly accessible.
The structure of the runtime config.json must match the shape of the
application's base configuration defined in config/default.json.
The nodes.homepage key controls what is rendered at the root URL (/):
"node"(default) — show the node view of the user's primary seed directly, as if the user had navigated to/nodes/<your-node>. The primary seed is resolved frompreferredSeeds(seedefault.json). This is the default so that a self-hosted deployment acts as a dedicated front-end for its own seed."landing"— serve the full Radicle marketing site: the landing page and its/learn,/installand documentation (/faq,/glossary,/guides/*) sub-routes. This is opt-in and intended for the canonical radicle.dev deployment; the marketing sub-routes are only reachable in this mode.
The cross-seed Explore page is always available at /explore, regardless of
the homepage setting.
default.json keeps homepage set to "node", so self-hosted deployments
are unaffected. The canonical radicle.network deployment opts into the
marketing site at build time without changing that default. To deploy
radicle.network, run npm run deploy.
If you operate your own seed node and want the explorer to act as a
dedicated front-end for it (the default behaviour), put your own node first
(and ideally as the only entry) in preferredSeeds so it is always picked
as the primary seed.
Example local.json:
{
"preferredSeeds": [
{
"hostname": "seed.example.com",
"port": 443,
"scheme": "https"
}
]
}With this configuration, opening / lands the visitor on the node view
for seed.example.com. Keeping preferredSeeds to a single entry
ensures the primary seed is deterministic; if you list multiple, users
are bucketed across them and may land on a different node.
radicle-httpd can map a short, human-readable alias to a repository ID
(RID), so a repository can be referred to by name instead of its full
rad: identifier. Aliases are configured on the node with the
--alias <name> <rid> flag, which may be repeated:
radicle-httpd --alias heartwood rad:z3gqcJUoA1n9HaHKufZs5FCSGazv5An alias works anywhere the RID is accepted: git clone, the HTTP API, the
raw endpoints, and Explorer URLs — the router resolves it transparently.
With the alias above, these two Explorer URLs point at the same repository:
https://radicle.network/nodes/seed.example.com/rad:z3gqcJUoA1n9HaHKufZs5FCSGazv5/issues
https://radicle.network/nodes/seed.example.com/heartwood/issues
and the repository can be cloned over Git by its alias:
git clone https://seed.example.com/heartwood.git- For detailed contribution guidelines, refer to the CONTRIBUTING.md file
- To propose changes, open an issue or submit a patch using Radicle
To get in touch with the maintainers, sign up to our official chat on Zulip.
The UI is distributed under the terms of GPLv3. See LICENSE for details.