solstone-tmux#

Standalone tmux terminal observer for solstone. Captures tmux terminal sessions to a local cache and syncs them to a solstone server.

Install#

pipx install solstone-tmux
# or
uv tool install solstone-tmux

Setup#

1. Register a remote observer on the solstone server#

sol remote create solstone-tmux

This prints the server URL and API key. You'll need both for the next step.

2. Write the config#

Create ~/.local/share/solstone-tmux/config/config.json:

{
  "server_url": "http://localhost:8000",
  "key": "<api-key-from-sol-remote-create>",
  "stream": "<hostname>.tmux",
  "capture_interval": 5,
  "segment_interval": 300
}

Set stream to <your-hostname>.tmux (e.g., fedora.tmux, archon.tmux). This matches the stream naming convention used by the built-in observers.

Alternatively, solstone-tmux setup runs an interactive wizard that prompts for the server URL and auto-registers.

3. Install the systemd service#

solstone-tmux install-service

This writes the unit file to ~/.config/systemd/user/solstone-tmux.service, enables it, and starts it.

4. Verify#

systemctl --user status solstone-tmux
solstone-tmux status
sol remote list  # should show the new remote as "connected"

Manual run#

solstone-tmux run         # foreground, ctrl-c to stop
solstone-tmux run -v      # verbose/debug logging

How it works#

• Polls all active tmux sessions every 5 seconds for content changes
• Accumulates captures in 5-minute segments under ~/.local/share/solstone-tmux/captures/
• Background sync service uploads completed segments to the solstone ingest API
• Captures offline — syncs when server becomes available
• Recovers incomplete segments on startup after crashes

Commands#

License#

AGPL-3.0-only. Copyright (c) 2026 sol pbc.