linux observer
Add INSTALL.md for agent-human collaborative setup
Instructions written for a coding agent working with a human.
Includes idempotency check, inline distro package lists,
sol root/observers clone path, and stream name as a
collaborative decision point.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
+83
+83
INSTALL.md
+83
INSTALL.md
···
1
+
# installing solstone-linux
2
+
3
+
these instructions are for a coding agent and human working together. solstone-linux is a standalone observer that captures screen and audio on linux desktops using PipeWire and GStreamer, and uploads to a solstone server.
4
+
5
+
solstone must already be installed and running. if it isn't, start there: https://solstone.app/install
6
+
7
+
## before you begin
8
+
9
+
if `sol` is not in PATH, check `~/.local/bin/sol` or use `.venv/bin/sol` inside the solstone repo.
10
+
11
+
check if solstone-linux is already installed and running:
12
+
13
+
```
14
+
systemctl --user status solstone-linux
15
+
sol remote list
16
+
```
17
+
18
+
if it's already active and connected, you're done.
19
+
20
+
## what to sort out together
21
+
22
+
- **system dependencies.** the observer needs PyGObject, GStreamer, and PipeWire bindings from system packages. installing these requires sudo.
23
+
- **stream name.** this identifies the capture source. the machine's hostname is the typical choice.
24
+
25
+
## install sequence
26
+
27
+
1. install system dependencies for your distro. if you need sudo, walk your human through it.
28
+
29
+
**fedora:**
30
+
```
31
+
sudo dnf install python3-gobject gtk4 gstreamer1-plugins-base gstreamer1-plugin-pipewire pipewire-gstreamer alsa-lib-devel pulseaudio-utils pipewire-pulseaudio
32
+
```
33
+
34
+
**debian / ubuntu:**
35
+
```
36
+
sudo apt install python3-gi gir1.2-gdk-4.0 gir1.2-gtk-4.0 gstreamer1.0-pipewire libasound2-dev pulseaudio-utils pipewire-pulse
37
+
```
38
+
39
+
**arch:**
40
+
```
41
+
sudo pacman -S python-gobject gtk4 gstreamer gst-plugin-pipewire libpulse alsa-lib
42
+
```
43
+
44
+
2. if not already cloned, clone into solstone's observers directory and install with pipx:
45
+
```
46
+
cd "$(sol root)/observers"
47
+
git clone https://github.com/solpbc/solstone-linux.git
48
+
cd solstone-linux
49
+
```
50
+
```
51
+
pipx install --system-site-packages .
52
+
```
53
+
`--system-site-packages` is required — the observer imports PyGObject and GStreamer bindings that only exist in system site-packages.
54
+
55
+
3. register the observer with solstone and save the API key:
56
+
```
57
+
sol remote create solstone-linux
58
+
```
59
+
60
+
4. write the config to `~/.local/share/solstone-linux/config/config.json`:
61
+
```json
62
+
{
63
+
"server_url": "http://localhost:5015",
64
+
"key": "THE_API_KEY_FROM_STEP_3",
65
+
"stream": "HOSTNAME"
66
+
}
67
+
```
68
+
69
+
5. install and start the systemd user service:
70
+
```
71
+
solstone-linux install-service
72
+
```
73
+
74
+
6. verify it's running and connected:
75
+
```
76
+
systemctl --user status solstone-linux
77
+
sol remote list
78
+
```
79
+
80
+
## notes
81
+
82
+
- activity detection (idle timeout, screen lock, power save) requires a GNOME desktop. other desktops capture screen and audio fine but won't get activity-based segment boundaries.
83
+
- if pipx is not installed: `pip install --user pipx` or install via your package manager.