TCP and UDP

A TCP / UDP request works below HTTP, with raw bytes. It has three modes: a Client that connects to a host over TCP, TLS or UDP and sends what you type; a Server that listens on a port, logs what clients send and can answer automatically; and Forward & Record, which sits between a client and a server and records every byte in both directions. Use it for line-based protocols such as Redis or SMTP, game and IoT protocols, checking that a port answers, or seeing exactly what a non-HTTP client sends.

Send bytes to a server

1. In the API client, click New › Other Protocols › TCP / UDP, or right-click a collection and choose Add Other Request › TCP / UDP. Search Everything (⇧ ⌘ A) also has New TCP / UDP Request.

2. Leave the mode on Client and choose TCP, TLS or UDP.

3. Type the target as host:port, for example tcp://localhost:6379 or api.example.com:443. A port is required.

4. Press ⌘ ↩ or click Connect.

5. Write a message, pick its Format and Line ending, and press ⌘ ⇧ ↩ or click Send. Replies appear in the Messages log.

6. Click Disconnect when you’re done.

1234567

Client mode with an HTTP request typed by hand, using escapes.

1. Mode: Client, Server or Forward & Record
2. Transport: TCP, TLS or UDP
3. Bytes sent and received
4. Target as host:port
5. How the composer text becomes bytes
6. Line ending added to text messages
7. Send (⌘⇧↩)

×

The mode and transport can only be changed while disconnected. The counters at the top right add up the bytes sent and received in this session.

Modes and transports

Mode	Transports	What it does
Client	TCP, TLS, UDP	Connects to the target and sends what you type. TLS wraps the TCP connection in TLS, and the log shows the protocol the server picked through ALPN, if any. UDP sends datagrams to the target and logs datagrams that come back from it.
Server	TCP, UDP	Listens on a port and logs every client and everything it sends.
Forward & Record	TCP, with optional TLS to the server	Listens on a local port and forwards each connection to another host and port, logging both directions.

The transport always comes from the picker; a scheme in the target, such as tcp:// or udp://, is only there for readability and can be left out. For the client, {{variables}} work in the target and the message. TLS connections verify the server’s certificate, so a server with a self-signed certificate is refused.

Compose a message

Control	Options	What it does
Format	Text	Sends the text as UTF-8, as typed.
	Text with escapes (\r \n \xHH) (default)	Text where backslash escapes become bytes: \r, \n, \t, \0, \a, \b, \f, \v, \e, \\, \", \', \xHH for any byte and \u{HHHH} for a Unicode character. An unknown escape is an error.
	Hex	Hex bytes, written as de ad be ef, 0xdeadbeef or de:ad:be:ef.
	Base64	Base64-encoded bytes.
Line ending	None, LF, CRLF (default), CR	Added after the message for the two text formats. Hex and Base64 are sent exactly as written.
Saved		Save Current Message keeps the composer text; choose a saved message to load it, or remove one with Delete.

The same six bytes, PING followed by a carriage return and line feed, written three ways:

Text with escapes

PING

With Line ending set to CRLF. Or leave the line ending at None and type PING\r\n.

Hex

50 49 4e 47 0d 0a

Base64

UElORw0K

With the defaults, the starter message GET / HTTP/1.1\r\nHost: example.com\r\n plus the CRLF line ending is a complete HTTP/1.1 request, which is a quick way to see a server’s raw answer.

Read the Messages log

Entry	Meaning
Connecting to host:port	The client started connecting.
Connected to … in 24 ms	The connection is up, with the remote address and, for TLS, the ALPN protocol.
128 bytes, outgoing or incoming	Data you sent (blue) or received (green).
The other side finished sending	The server closed its side of a TCP connection.
Closed / Error	The connection ended or failed, with the reason.

Select an entry to see its contents below: printable data as text, binary data as a hex dump, and JSON as a tree. Data arrives in the chunks the network delivered, so one reply can span several entries. Hide events hides informational entries, the search field filters, and Clear empties the log.

Run a test server

Use Server to see what a client sends, or to stand in for a service that isn’t running yet.

1. Set the mode to Server and choose TCP or UDP.

2. Set Listen on port (default 9000).

3. Leave All interfaces unchecked to accept connections only from this Mac, or check it to let other devices on your network connect.

4. Choose an Auto reply:

   Option	What the server does with each message it receives
   None	Nothing; it only logs.
   Echo	Sends the same bytes back.
   Fixed	Sends the Reply text, which supports the escapes above. The default is OK\r\n.

5. Click Start. The bar shows Listening · 0 connected, and the count goes up as clients connect.

6. Point your client at localhost:9000. Each client gets a number in the log: Client #1 connected from …, #1 · 42 bytes, Client #1 disconnected. For UDP, each distinct sender address counts as a client.

7. To answer by hand, write a message and click Send. It goes to the most recently connected client.

8. Click Stop to stop listening.

Forward and record a connection

Forward & Record shows the exact bytes a client and server exchange, for protocols Cloak Proxy’s HTTP proxy can’t see, such as Redis, PostgreSQL, game servers or IoT devices.

1. Set the mode to Forward & Record.

2. Set Listen on (default 9000), the host and port to forward to (default localhost and 6379, the Redis port), and check TLS upstream if the real server expects TLS.

3. Click Start. The log shows Forwarding localhost:9000 → localhost:6379.

4. Point your client at localhost:9000 instead of the real server. For example, redis-cli -p 9000.

5. Use the client normally. Each connection is logged as Connection from …, then every chunk as client → server · N bytes or server → client · N bytes, then Connection closed.

6. Click Stop when you’re done.

The forwarder only listens on 127.0.0.1, so only apps on this Mac can use it. Send isn’t available in this mode.

Run TCP requests in the collection runner

The collection runner and cloakctl run Client requests only; servers and forwarders wait for connections, so the runner skips them (or reports TCP / UDP servers and forwarders wait for connections, so they can’t run here). A run connects, sends the composer message once (encoded with its format and line ending), collects what comes back until the line has been quiet for half a second or the request timeout passes, and disconnects.

Response part	Value
Status	200 OK
Content-Type	text/plain; charset=utf-8 when the reply is valid UTF-8, application/octet-stream otherwise.
Content-Length	The number of bytes received.
Body	Every byte received, joined together.

A target without a port (Use host:port, e.g. tcp://localhost:7) or a refused connection is reported as an error with no response.

TCP / UDP requests have no Scripts tab of their own. Put tests in the collection’s or a folder’s post-response script, and check pm.info.requestName for tests meant for one request:

Collection post-response script

if (pm.info.requestName === "Redis PING") {
  pm.test("Redis answers PONG", () => {
    pm.expect(pm.response.text()).to.eql("+PONG\r\n");
  });
}

For that test, the request’s message is PING with the CRLF line ending, sent to tcp://localhost:6379.

Listening on all interfaces

With All interfaces checked, any device that can reach your Mac can connect to the test server and send it data, and with Echo or Fixed it answers. Leave it unchecked unless you need another device to connect, and click Stop when you’re done. Only send traffic to hosts and ports you’re allowed to test.

Related

MQTT requestsTalk to IoT brokers with a full MQTT client.

WebSocket requestsTwo-way messages over WebSocket.

Apps that ignore the proxyCapture HTTP from apps that skip the system proxy.

Collection runnerRun TCP checks with tests.