wallhack

REST API

The REST API provides programmatic control of entry nodes. It uses the same TLS certificate as the tunnel and supports Basic authentication.

Enabling the API

Pass --api <addr> when starting an entry node:

wallhack daemon --role entry --listen :443 --api 127.0.0.1:6564

Basic authentication is required. A random secret is generated at startup and printed to stdout: 

info: REST API listening on https://127.0.0.1:6564
info: REST API username: admin
info: REST API secret:   K7mXpQ2nR9sY4wZtBvLjC6dHfAuE3aNp

To set fixed credentials, use --api-user and --api-secret: 

wallhack daemon --role entry --listen :443 --api 127.0.0.1:6564 --api-user operator --api-secret mysecret

The API is served over HTTPS. A self-signed certificate is auto-generated unless --cert and --key are provided.

Example Usage

SECRET=K7mXpQ2nR9sY4wZtBvLjC6dHfAuE3aNp  # from startup output

# Get stats
curl -k -u admin:$SECRET https://localhost:6564/stats

# List peers
curl -k -u admin:$SECRET https://localhost:6564/peers

# Add a route through a peer
curl -k -u admin:$SECRET -X POST https://localhost:6564/routes \
  -H 'Content-Type: application/json' \
  -d '{"cidr": "192.168.1.0/24", "peer": "bench"}'

Endpoints

get /health

Process health

Verifies that the node process is active and responding. Always returns 200. No authentication required.

get /info

Node info

Retrieves node identity, role, capabilities, and uptime.

Response

name string Node name (set via --name).
version string Binary version string including git SHA and build timestamp.
role "entry" | "exit" | "relay" | "indeterminate" Operational role of this node.
uptime_ms integer Node uptime in milliseconds.
peer_addr string Remote peer address (present only when connected).
listen_addr string Bound listen address (present only when listening).
capabilities object
get /logs

Recent daemon logs

Retrieves recent log lines from the daemon's in-memory ring buffer (last 200 lines max).

Response

lines array Recent daemon log lines, oldest first.
get /stats

Traffic metrics

Retrieves current traffic volume and flow statistics.

Response

bytes_in integer Total bytes received by the node.
bytes_out integer Total bytes transmitted by the node.
packets_in integer Total packets received by the node.
packets_out integer Total packets transmitted by the node.
active_connections integer Number of currently active peer connections.
active_flows integer Number of active L4 network flows being tracked.
packets_dropped integer Total packets dropped since daemon start.
total_connections integer Total peer connections opened since daemon start (monotonically increasing).
total_flows integer Total L4 flows opened since daemon start (monotonically increasing).
get /peers

List connections

Retrieves a list of all currently connected peers.

Response

peers PeerResponse[] List of all currently connected peers.
delete /peers/{id}

Disconnect peer

Terminates the connection with a specific peer. Accepts the peer's unique id (from GET /peers) or an unambiguous name prefix.

Parameters

id string Peer id (or unambiguous name prefix) to disconnect.

Response

success boolean Indicates if the requested operation completed successfully.
message string Optional detail providing context for success or failure.
get /routes

List routing table

Retrieves all active routing entries established through this node.

Response

routes RouteResponse[] List of active routing entries.
post /routes

Add route

Configures a new route to a target network through an active peer.

Body

cidr string Target network in CIDR notation (e.g., 10.0.0.0/24).
peer string Name of the peer through which the network should be routed.

Response

success boolean Indicates if the requested operation completed successfully.
message string Optional detail providing context for success or failure.
get /events

Event stream

Server-Sent Events stream of peer lifecycle events (connect/disconnect). The stream sends `peer_connected` and `peer_disconnected` events with JSON payloads. Keep-alive comments are sent every 15 seconds.

delete /routes/{cidr}

Delete route

Deletes a routing entry by its network specification.

Parameters

cidr string URL-encoded CIDR specification (e.g., 10.0.0.0%2F24).

Response

success boolean Indicates if the requested operation completed successfully.
message string Optional detail providing context for success or failure.
post /connect

Connect to peer

Initiates an outbound connection to a remote peer.

Body

addr string Remote peer address to connect to (e.g., quic://1.2.3.4:4433).

Response

peer_addr string Resolved remote peer address.
protocol string Transport protocol used (QUIC or WebSocket).
post /listen

Start listener

Begins accepting inbound peer connections on the given address.

Body

addr string Address to listen on (e.g., quic://0.0.0.0:4433).

Response

listen_addr string Actual bound address (important if port was 0).
protocol string Transport protocol used (QUIC or WebSocket).
fingerprint string Certificate fingerprint (SHA-256) for peer verification.
post /disconnect

Disconnect transport

Tears down the active transport session (both connect and listen).

Response

success boolean Indicates if the requested operation completed successfully.
message string Optional detail providing context for success or failure.
post /shutdown

Shutdown daemon

Initiates graceful shutdown of the daemon process.

Response

success boolean Indicates if the requested operation completed successfully.
message string Optional detail providing context for success or failure.
put /role

Set role

Set or clear this node's role. Use role=auto to clear all preferences and return to negotiation.

Body

role "auto" | "entry" | "exit" | "relay" Target role, or "auto" to clear all preferences.
level "prefer" | "exclude" | "fixed" How to apply: fixed (default, force), prefer (soft), exclude (avoid).

Response

success boolean Indicates if the requested operation completed successfully.
message string Optional detail providing context for success or failure.