Alpha Testing Guide¶

Kunuleco is in closed alpha. The system runs and people use it every day, and it is also still being built. This page says what that means for you and how to report what you find.

What "alpha" means here¶

Rough edges are normal. Commands sometimes misbehave and output is sometimes untidy. Reconnecting after a laptop sleeps can take a nudge. When something looks stuck, /reconnect or a restart of the app is a fair move.
Releases move fast. /check-updates shows which components have updates, and /update installs them. The installer checks the signature on a release's manifest before it uses it, and it refuses a manifest whose signature does not verify.
Some releases need a fresh start. Now and then a release changes something foundational, and an update in place is not enough.
Treat alpha data as precious but not yet promised. Your spaces are kept on your node and survive restarts, but there is no durability guarantee yet. Keep copies of anything you would hate to lose. To back up your identity, type export-identity on its own in the Urchin client, which opens a form for it.

A note on security¶

The design is capability-based and releases are signed. It is also alpha software that has not had an independent audit, and some of its checks are incomplete (see Known Issues). On a local network, messages between nodes are signed but not encrypted. Live voice is not end-to-end encrypted, and Tor gives a node reachability, not location privacy. Use Kunuleco for conversation among people you trust, not for secrets or for high-risk situations.

Alpha Testing Documents¶

Document	Purpose
What to Expect	Current state, limitations, known issues
Test Scenarios	What to test and how
Reporting Issues	How to give useful feedback
Known Issues	Current bugs and workarounds

Two Ways In¶

You use Kunuleco through the Urchin client or over SSH.

The Urchin client is the graphical app. It has a terminal where you type node commands directly. Commands that start with / belong to the client itself and do not reach the node.
SSH reaches the same node commands from any SSH client, with ssh <user>@<host> -p 8122. Over SSH you type commands with no / prefix, and the client's / commands do not exist.

The kunuleco program on your machine only starts the node. It takes no subcommands, so a line such as kunuleco invite create does nothing useful. Every command on these pages is typed into the Urchin terminal or an SSH session. The Command reference lists them on one page.

Quick Start for Testers¶

1. Install¶

Download the Urchin executable for your platform and urchin.pck into the same folder, then launch the executable. On macOS the download is a single zipped app bundle. On a machine with no Kunuleco installation, Urchin runs a setup wizard that installs the node, Veilid, Tor and IPFS. Installation covers each platform.

2. Verify¶

In the Urchin terminal:

/check-updates
transport
@node_processes

/check-updates lists the components that have updates. transport shows which transports are running and whether each can carry connections. @node_processes shows which daemons are running.

3. Create Identity¶

On the Urchin welcome screen, enter a username and choose Create Identity, then set a password and a theme. The first account on a new node becomes that node's owner. There is no password reset.

Then check who you are:

whoami

4. Look Around¶

look
help
help all

look describes where you are. help shows the commands to start with, and help all lists the rest.

5. Test Connections¶

If you have another machine or a friend testing, one side creates a presence and an invite:

create ~presence plaza
invite plaza

invite replies with a short code of two words and a number. Send the code to the other person, and they run:

join <code>

Then either side can talk with chat <message>.

What's Working¶

Feature	Status	Notes
Identity creation	Working	Your node creates it with your account. A signed hello proves who a peer is
Accounts	Working	Username and password. The first account is the node's owner, and later accounts need a sponsor
Halls	Working	Found, steward, admit the people who knock
Capsules	Working	Create, store objects, grant capabilities
Presences	Working	Keep one open or make it invite-only with `door`
mDNS	Working	Same-network discovery. The signed hello decides who a peer is
Veilid	Working	Connections across the internet
Tor	Working	Reachability across NAT, not location privacy
IPFS	Impaired	Stores the media you upload, but does not carry connections yet
CapTP	Working	Messaging protocol
Persistence	Working	SQLite storage

What Needs Testing¶

Current priorities:

Multi-node communication. Do messages reliably flow between nodes?
Transport fallback. Does the system recover when transports fail?
Persistence. Does state survive restarts correctly?
Error messages. Are failures understandable?
Edge cases. What happens with unusual input?

How to Help¶

Capture the problem first. Type /bug <what went wrong> in the Urchin terminal right after it happens, or bug <what went wrong> over SSH. It writes a JSON snapshot to a bugs folder and prints the file's path and an 8-character id. It sends nothing anywhere. From the Urchin client there are two files with the same id, one from the client and one from the node, and you should send both.

Then send the files through your alpha channel with a note that covers:

Exact reproduction steps. What did you do, in order?
Expected and actual. What should have happened, and what happened instead? Paste the output if you can.
Environment. Your OS, the versions from /about and @version, and what transport showed if it looks network-related.

For anything the capture cannot see, such as a crash at startup or trouble with the installer, describe it in your alpha channel directly. See Reporting Issues for what each file holds.

Communication¶

Email: alpha@kunul.eco
Discord: https://discord.gg/U8xa4mqMNp

Thank You¶

Alpha testing takes time and patience. Small observations are welcome, and "this wording confused me" is a real bug.