dumbgoy/soulseek-rs-modded
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: put daemon mode on the website and tighten the README

Browse Source 
The website made three claims daemon mode falsifies — "No TTY, no daemon",
"no daemon, no MCP server, no API key", and "no GUI and no daemon mode yet"
under what-this-is-not. All three corrected.

Adds a docs section and a home feature card, both leading with the reason
rather than the mechanics: the server allows one session per account, so
parallel one-shot commands either displace each other or mean a throwaway
username per run, which is account churn on infrastructure other people
maintain. A daemon is one login for as long as you work.

The README section said that three times over and buried the reasoning below
the mechanics; rewritten to state it once, up front. It now also covers which
commands stay local and that shares add reaches a running daemon, which was
meant to land earlier and silently did not — the edit anchored on text that
only existed in SKILL.md.
This commit is contained in:
Michel de Graaf
2026-07-27 14:04:14 +02:00
parent fe56a070e1
commit 3f914c4425
4 changed files with 94 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+25 -24
View File
@@ -118,10 +118,8 @@ Everything else is a one-shot command that runs headless.
### Daemon mode
A one-shot command logs in, does its job, and exits, which means nothing
outlives it and two commands at once fight over the server's one-session-per-
account rule. Run a daemon instead and it holds the session while everything
else borrows it:
A one-shot command logs in, does its job, and exits. Run a daemon instead and
it holds the session while everything else borrows it:
```bash
soulseek-rs daemon # stays in the foreground; leave it running
@@ -129,8 +127,21 @@ soulseek-rs search 'aphex twin' # no login, no flags — uses the daemon
soulseek-rs # the TUI attaches to the same session
```
From a script, start it and wait for it — it takes a second or two to log in,
and a command that arrives early opens a session of its own instead:
**Why you want this.** The server allows one session per account. Without a
daemon, two commands at once either cut each other off or push you into a
throwaway username per run — account churn on infrastructure other people
maintain and share. A daemon is one login for as long as you work, and one
share index instead of a rescan every invocation. It also lets a download
outlive the command that queued it, and keeps collecting chat while nothing is
attached. If you drive this from a script or an agent, start one.
Commands find it by themselves. It listens on a Unix socket only your user can
open, so there is nothing to configure and no secret to pass around — the same
arrangement Docker and ssh-agent use. With no daemon running, everything
behaves exactly as it did before; `--no-daemon` forces that for one run.
From a script, start it and *wait* for it: it takes a second or two to log in,
and a command that arrives early opens a session of its own instead.
```bash
soulseek-rs daemon status --json >/dev/null 2>&1 || {
@@ -142,28 +153,18 @@ soulseek-rs daemon status --json >/dev/null 2>&1 || {
}
```
Commands find it by themselves. The daemon listens on a Unix socket only your
user can open, so there is nothing to configure and no secret to pass around —
the same arrangement Docker and ssh-agent use. With no daemon running,
everything behaves exactly as it did before; `--no-daemon` forces that for one
run.
What this buys: downloads that outlive the command that queued them, several
clients (or agents) on one account at once, and a chat window that keeps
collecting while nothing is attached.
It is also the neighbourly way to use the network. The server allows one
session per account, so parallel one-shot runs either displace each other or
push you into registering a throwaway name per run — account churn on
infrastructure other people maintain. A daemon is one login for as long as you
work, and one share index instead of a rescan per invocation. If you are
driving this from a script or an agent, start a daemon.
```bash
soulseek-rs daemon status # who it is, what it shares, who is attached
soulseek-rs daemon stop
```
Everything that touches the network goes through it. `config`, `skills`,
`completions` and `portmap` stay local, because they are about this machine
rather than a session. `shares add`/`remove` do both: they write the config
file *and* update a running daemon, so a folder is served straight away rather
than at its next start. Files land on the *daemon's* filesystem — `daemon
status` reports where.
For a client on another machine, bind a TCP port as well and give it the
token:
@@ -173,7 +174,7 @@ soulseek-rs daemon token # the secret that connection needs
```
There is no transport encryption, so put SSH or a TLS proxy in front of
anything non-loopback. Note that files land on the *daemon's* filesystem.
anything non-loopback.
Third-party clients are first-class: the daemon speaks newline-delimited
JSON-RPC 2.0 described by an [OpenRPC](https://open-rpc.org) document
website/src/pages/community.tsx
+1 -2
View File
@@ -194,8 +194,7 @@ export const Community = () => {
eyebrow="what this is not"
title="Three good clients to point you elsewhere."
>
soulseek-rs has no GUI and no daemon mode yet. If one of these fits you better,
use it.
soulseek-rs has no graphical interface. If one of these fits you better, use it.
</SectionHead>
<div className="grid grid-cols-1 gap-3.5">
{ALTERNATIVES.map((alt) => (
website/src/pages/docs.tsx
+51 -3
View File
@@ -171,12 +171,13 @@ const FromTheShell = () => (
<p>
The command groups: <Code>search</Code>, <Code>get</Code>, <Code>download</Code>,{' '}
<Code>browse</Code>, <Code>room</Code>, <Code>message</Code>, <Code>serve</Code>,{' '}
<Code>user</Code>, <Code>whoami</Code>, <Code>shares</Code>, <Code>config</Code>,{' '}
<Code>portmap</Code>, <Code>skills</Code>, <Code>completions</Code>. Records are
<Code>user</Code>, <Code>whoami</Code>, <Code>shares</Code>, <Code>daemon</Code>,{' '}
<Code>config</Code>, <Code>portmap</Code>, <Code>skills</Code>,{' '}
<Code>completions</Code>. Records are
tab-separated fields, one per line, or NDJSON with <Code>--json</Code>.
</p>
<p>
No TTY, no daemon. <Code>search --json</Code> pipes through <Code>jq</Code> into{' '}
No TTY required. <Code>search --json</Code> pipes through <Code>jq</Code> into{' '}
<Code>download --stdin</Code>. Every ending has its own exit code: 4 found
nothing, 3 could not reach the server, 6 the transfer died.
</p>
@@ -222,6 +223,52 @@ const FromTheShell = () => (
</Section>
)
const Daemon = () => (
<Section>
<SectionHead eyebrow="5 · the daemon" title="One login, however many commands.">
Soulseek allows one session per account. Run a daemon and everything else borrows
it &mdash; no second login, nothing to configure.
</SectionHead>
<Cols start>
<Terminal
label="shell"
lines={[
{ t: 'cmd', text: 'soulseek-rs daemon &' },
{ t: 'cm', text: '# once; it holds the session' },
{ t: 'cmd', text: 'soulseek-rs search "netlabel 2004" --json' },
{ t: 'cm', text: '# no login, no flags — it finds the daemon' },
{ t: 'cmd', text: 'soulseek-rs' },
{ t: 'cm', text: '# the TUI attaches to the same session' },
{ t: 'cmd', text: 'soulseek-rs daemon status' },
{ t: 'cmd', text: 'soulseek-rs daemon stop' },
]}
/>
<Prose>
<p>
Commands find it themselves: it listens on a Unix socket only your user can
open, so there is no address to pass and no token to handle. Without one
running, everything behaves exactly as it did before.
</p>
<p>
Why bother: the server permits a single session per account, so two one-off
commands at once either cut each other off or push you into a throwaway
username per run &mdash; account churn on a network other people maintain. A
daemon is one login for as long as you work, one share index instead of a
rescan every invocation, and downloads that outlive the command that queued
them. If you drive this from a script or an agent, start one.
</p>
<p>
It speaks newline-delimited JSON-RPC 2.0 described by an{' '}
<Code>openrpc.json</Code> the daemon serves itself, so a client generator gives
you one in any language. <Code>daemon --bind</Code> adds a TCP port for other
machines; those need the token from <Code>daemon token</Code>, while the local
socket never does.
</p>
</Prose>
</Cols>
</Section>
)
const TheRest = () => (
<Section band>
<Panel title="the rest" className="bg-raised [&>span]:bg-panel">
@@ -257,6 +304,7 @@ export const Docs = () => (
<Layout />
<Keys />
<FromTheShell />
<Daemon />
<TheRest />
</>
)
website/src/pages/home.tsx
+17 -2
View File
@@ -59,6 +59,19 @@ const FEATURES = [
</>
),
},
{
glyph: '◈',
color: 'var(--accent-text)',
title: 'Daemon mode',
cmd: 'soulseek-rs daemon',
body: (
<>
Hold one session and let every other command borrow it &mdash; the network allows
one login per account, so this is the neighbourly way to run several at once. It
speaks JSON-RPC, so other tools can drive it too.
</>
),
},
{
glyph: '›',
color: 'var(--status-info)',
@@ -276,8 +289,10 @@ const Agents = () => (
queueing behind before a 2 GB transfer.
</p>
<p>
It stays a CLI: no daemon, no MCP server, no API key. Upgrading the binary upgrades
the skill; rerun <Code>skills install</Code> to take it.{' '}
It stays a CLI: no MCP server, no API key. The skill tells your agent to start a
daemon first, so a batch of parallel requests is one login rather than one per
command. Upgrading the binary upgrades the skill; rerun <Code>skills install</Code>{' '}
to take it.{' '}
<Link to="/docs" className="text-link hover:text-link-hover">
See the commands
</Link>