Socket API

Namu exposes a newline-delimited JSON-RPC 2.0 API over a Unix domain socket. The default socket path is /tmp/namu.sock. Tagged debug builds use /tmp/namu-<tag>.sock.

Transport

• Protocol: JSON-RPC 2.0
• Socket type: Unix domain socket (local) or TCP with HMAC-SHA256 auth (remote relay)
• Framing: one JSON document per line
• Request IDs: string or number
• Notifications: request without an id

Access Control Modes

Request Example

{"jsonrpc":"2.0","id":"1","method":"system.ping","params":{}}

Response Example

{"jsonrpc":"2.0","id":"1","result":{"pong":true}}

Ref IDs in Responses

All responses that return an id (UUID) also include a ref field with the short form (workspace:1, pane:2, surface:3). Clients may send either form as input.

Core Namespaces

Sidebar Status API

Status entries appear as colored pills in the workspace sidebar. Useful for build monitoring, CI/CD status, and agent coordination.

// Set a status entry
{"jsonrpc":"2.0","id":"1","method":"sidebar.set_status","params":{
  "key": "build",
  "value": "Tests passing",
  "icon": "checkmark.circle.fill",
  "color": "#34C759",
  "priority": 10
}}

// Set a progress bar
{"jsonrpc":"2.0","id":"2","method":"sidebar.set_progress","params":{
  "value": 0.75,
  "label": "Building (75%)"
}}

// Append a log entry
{"jsonrpc":"2.0","id":"3","method":"sidebar.log","params":{
  "message": "All tests passed",
  "level": "success",
  "source": "ci"
}}

Browser Commands (84 methods)

• Navigation — navigate, back, forward, reload, stop, go
• DOM Interaction — click, type, hover, focus, blur, get-text, get-attr, get-property
• Screenshots & Images — screenshot, get-image, save-image
• JavaScript Execution — eval, eval-function, eval-async, eval-generator
• Tab Management — list-tabs, new-tab, close-tab, activate-tab, switch-tab
• History & Search — history, clear-history, find (with history scoring)
• Profile Management — list-profiles, create-profile, delete-profile, get-profile
• Cookie & Storage — get-cookies, set-cookies, clear-cookies, get-local-storage, set-local-storage
• Performance & Debugging — get-performance-metrics, enable-devtools, disable-devtools
• Window & Frame — get-window-size, set-window-size, list-frames, switch-frame

Server-Push Events

Subscribed clients receive JSON-RPC notifications for these event families:

• process.exit
• output.match
• port.change
• shell.idle
• workspace.change

TCP Relay Transport

Remote access uses an authenticated TCP relay with HMAC-SHA256 challenge-response authentication. The relay multiplexes requests to the local command dispatcher.

Relay security properties:
- HMAC-SHA256 authentication (CryptoKit constant-time comparison)
- Relay credential hex validation (malformed tokens rejected at parse time)
- Response size cap: 1MB
- Proxy header size cap: 64KB
- Cloud metadata SSRF blocking (169.254.169.254)
- Atomic metadata file writes (no partial-write races)

Use system.relay_status to inspect relay availability and health.

Environment Variables