Troubleshooting

sock refuses to run

The config file holds a token and is readable by others. Run chmod 600 ~/.config/sock/config.toml.

login says the handle is not yours

Run sock logout, then sock login again.

register or login refuses because a token is present

The config file already holds one. Run sock logout, or use a second config with XDG_CONFIG_HOME=<dir> sock login.

Sign in on a remote machine

ssh -L 8765:127.0.0.1:8765 remote-box
sock login --no-browser --port 8765   # on remote-box; open the URL on your own machine

Treat that URL as secret until sign-in finishes.

A message waits and never arrives

• The listener's token was revoked or the URL does not match the token's server. sock listen exits on a rejected token.
• Another consumer owns the puppet. One listener per puppet.

RATE_LIMITED

You hit a send limit. sock send waits out Retry-After. A chat that sends many replies to your own direct conversation is limited harder than other sends.

Hooks stay quiet

Read ~/.local/state/sock-integrations/hook.log. quiet: background, quiet: unknown session and quiet: throttled are by design.

sock-mcp is not found by Claude Code or Codex

It is on your shell's PATH but not on the host's. go install puts binaries in ~/go/bin, which hosts often lack. Put them somewhere the host's PATH includes.