Skip to content

Unix socket

If your Solana app and rpc-plane run on the same host, you can bind to a Unix domain socket instead of a TCP port. This eliminates the loopback TCP stack entirely.

Configuration

Set server.listen to an absolute or relative file path:

[server]
listen         = "/run/rpc-plane/proxy.sock"  # absolute path
metrics_listen = "127.0.0.1:9401"             # metrics always stays on TCP

./rpc-plane.sock (relative path) also works. rpc-plane detects a Unix socket path by the leading / or ./; anything else is treated as a host:port.

On startup, any stale socket file at that path is removed automatically so restarts don't require manual cleanup.

Connecting your app

Pass the socket path as the URL using the http+unix scheme, or use curl --unix-socket for ad-hoc testing:

# Health check
curl --unix-socket /run/rpc-plane/proxy.sock http://localhost/health | jq

# RPC call
curl --unix-socket /run/rpc-plane/proxy.sock \
     -X POST http://localhost \
     -H 'Content-Type: application/json' \
     -d '{"jsonrpc":"2.0","id":1,"method":"getSlot"}'

For rpc-plane status, the CLI detects the socket path from your config and prints the correct curl command automatically.

Most Solana client libraries accept a plain http:// URL — proxy the socket through socat if the library doesn't support http+unix:

socat TCP-LISTEN:9400,fork,reuseaddr UNIX-CLIENT:/run/rpc-plane/proxy.sock

Why it's faster

Scenario req/s p99 p99.9
Direct TCP to backend 20 169 27.32 ms 41.06 ms
TCP proxy 15 654 32.23 ms 49.80 ms
UDS proxy 26 434 8.70 ms 10.89 ms

Two things compound here:

  1. No loopback TCP stack. The client→proxy hop goes through the kernel's Unix socket path, skipping IP routing, TCP state machines, and Nagle (which has no effect on Unix sockets anyway).
  2. Connection pooling. The proxy→backend hop reuses pooled TCP connections. The load test's direct-TCP baseline opens a fresh connection per request, so the UDS proxy beats it even on raw throughput.

Tail latency is the biggest win: p99 drops from 32 ms to 8.7 ms and p99.9 from 49 ms to 10.9 ms compared to the TCP proxy.

Permissions

The socket file inherits the umask of the rpc-plane process. If your app runs as a different user, either:

  • Run both under the same Unix group and set umask 0117 (owner + group read/write), or
  • Set explicit permissions after startup: chmod 660 /run/rpc-plane/proxy.sock

For systemd, RuntimeDirectory=rpc-plane creates /run/rpc-plane with the correct owner automatically.

Limitations

  • Unix sockets are only supported on Unix platforms (Linux, macOS). The binary refuses to start with a socket path on Windows.
  • The metrics endpoint (server.metrics_listen) always binds to TCP — it is not affected by this setting.
  • server.listen_backlog has no effect on a Unix socket (it is a TCP-only setting).