AgentNoise

1. What AgentNoise is

AgentNoise is a native desktop helper for talking to local coding agents from a phone. It uses White Noise as the private chat surface, then launches local tools through the same launcher stack used everywhere else on this site.

The design goal is narrow: a phone can ask for work, AgentNoise authenticates and routes the request, and the workstation decides what the agent process is allowed to touch.

2. Architecture

Each White Noise group id maps to its own AgentNoise session, so multiple chats can keep separate selected repos, working directories, jobs, and prompt context.

3. Install path

The intended packaged path is Homebrew. If the tap release is available, install and start the service:

brew install nvk/tap/agentnoise
brew services start nvk/tap/agentnoise
agentnoise up

agentnoise up is both the first-run command and the local console. If the service already owns the listener, it attaches and follows logs. If no listener is running, it takes the foreground lock and runs the same engine itself.

From source:

git clone https://github.com/nvk/agentnoise.git
cd agentnoise
cargo build --release
target/release/agentnoise up

If wn and wnd are not packaged beside AgentNoise, install the White Noise CLI tools into AgentNoise's managed data directory:

agentnoise whitenoise install

4. Pair the phone

1. Start agentnoise up from a normal user terminal or service context.
2. Scan the desktop QR from White Noise on the phone.
3. Create a White Noise chat with the AgentNoise desktop identity.
4. Send the 6-digit PIN shown on the desktop as the first phone message.
5. Send /status, then /help.

During first pairing, AgentNoise ignores messages until the PIN succeeds. After that it saves the phone sender to the allowlist.

5. Chat commands

AgentNoise commands are not shell text. They are narrow chat verbs mapped to structured argv arrays.

/status
/repos
/use sandbox
/pwd
/codex fix the failing test
/claude review the last change
/jobs
/tail <job>
/cancel <job>

Repos are aliases from config, not arbitrary paths sent from the phone. A plain /codex or /claude uses the current selected repo for that White Noise chat.

6. Security rules

• Use a dedicated White Noise desktop identity for AgentNoise.
• Keep the helper nsec in the OS keychain for normal use.
• Require first-pairing PIN auth before accepting any sender.
• Use repo aliases, not phone-provided filesystem paths.
• Route agent execution through bondage profiles.
• Keep default profiles sandboxed; make wider profiles explicit.
• Use local job logs, /tail, and /cancel instead of dumping raw process output into chat.

7. Optional Hermes

Hermes support is a backend, not a second messaging gateway. Keep White Noise as the phone control plane and launch Hermes through its own bondage profile.

[agents.hermes]
enabled = true
profile = "hermes"
bin = "hermes"

bondage exec hermes ~/.config/bondage/bondage.conf -- \
  hermes chat --quiet --source agentnoise --toolsets skills -q "<prompt>"

Put HERMES_HOME, model endpoint settings, toolsets, and filesystem policy in the Hermes profile. Start narrow, then widen only after the local profile behaves.

8. Troubleshooting