Installation¶
Getting Kunuleco running on your machine.
Download Urchin¶
Urchin is the Kunuleco client. Your node, the part that holds your account and your places and talks to other nodes, comes with it, and Urchin installs and runs it for you. Kunuleco is in closed alpha, so the downloads page is open to alpha testers, and your welcome note has the link.
| Platform | Files to download |
|---|---|
| Windows | urchin.exe and urchin.pck |
| Linux | urchin.x86_64 and urchin.pck |
| macOS (Apple Silicon) | urchin-macos-arm64.zip |
| macOS (Intel) | urchin-macos-x64.zip |
On Windows and Linux the executable and urchin.pck must sit in the same folder, or Urchin will not start. On macOS,
unzip the archive. The content package is inside Urchin.app. Windows and Linux are supported. macOS is experimental
and untested.
Launch it¶
- Windows: double-click
urchin.exe. If SmartScreen appears, click More info, then Run anyway. - Linux: in a terminal in that folder, run
chmod +x urchin.x86_64and then./urchin.x86_64. - macOS: double-click
Urchin.app. If macOS blocks it, open System Settings → Privacy & Security and click Open Anyway next to the Urchin entry.
These warnings appear because Urchin is not code-signed yet.
First-run setup¶
On a machine with no Kunuleco installation, Urchin runs a setup wizard. It sets up a Python environment, the Kunuleco node, and the Veilid, Tor and IPFS programs the node uses to reach other nodes. Urchin carries these inside its content package and installs from that copy, so a fresh install does not need to download them. If the copy is missing, setup downloads from the network instead and says so in its log. Setup can take several minutes. Let it finish without closing the window. When it is done, the node is running and Urchin connects to it.
If you have run Urchin before, it finds the existing installation and connects straight away.
What gets installed¶
| Component | Purpose |
|---|---|
| The Kunuleco node | Runs your account, your places and your connections |
| IPFS (kubo) | Content storage |
| Veilid | Reaching other nodes across the internet |
| Tor | Reaching other nodes across NAT, as a fallback |
They are separate copies with their own ports, so they do not conflict with an IPFS or Tor you already run. The node starts them itself whenever it starts, so there is nothing to run by hand.
Where it lives¶
| Platform | Location |
|---|---|
| Windows | %LOCALAPPDATA%\Kunuleco\ |
| Linux | ~/.local/share/kunuleco/ |
The node's settings file is config.json in that folder. See the configuration reference.
How Urchin checks what it installs¶
Every release is described by a signed manifest, and Urchin carries the key that checks it. A manifest that does not verify is refused, and nothing is installed or updated from it. The copy of the manifest inside the content package is checked the same way, which is how a fresh install verifies without the network.
Keeping it up to date¶
Type these in Urchin's terminal:
| Command | What it does |
|---|---|
/check-updates |
Shows which components have updates |
/update |
Updates everything, the client included |
/update client |
Updates the Urchin client |
/update kunuleco |
Updates the node |
/update veilid · /update tor · /update ipfs |
Updates one of the programs the node uses |
/restart |
Restarts Urchin, for example after a client update |
/reinstall |
A clean reinstall, for when something is broken |
Start with /check-updates.
Some alpha releases change something foundational, and then /update is not enough and a fresh install is needed. The
release notes say so when that happens. Back up your identity first (see
Identity management).
If something goes wrong¶
- Setup stalls: check your connection. Some networks block peer-to-peer traffic, so try another network. Close and relaunch Urchin, and setup resumes.
- Veilid or Tor will not connect: Veilid needs an accurate system clock. Corporate and school networks often block peer-to-peer traffic.
- Nothing works: run
/reinstall. If Urchin will not start at all, delete the Kunuleco folder above and relaunch. ⚠️ That folder holds your account. Back up your identity first (see Identity management).
For more, see Troubleshooting.
Running a node without Urchin (developers)¶
The node can also run without the client, for development or on a server. The kunuleco command starts the node. It
has no subcommands, and everything else is done by connecting to the node from Urchin or over SSH. QUICKSTART.md at
the top of the source repository covers setting a node up this way.
Next Step¶
With Urchin running, create your account.