How to capture HTTPS traffic and get started with Microkoi

01 Installation

The beta runs on macOS 13 or later, Windows 10 and 11, and Linux. No sign-up or key needed.

The beta is built without paid signing certificates, so your system warns about an unknown developer on first launch. On macOS open the app with a right-click and Open; on Windows click More info and Run anyway.

The beta interface is in Russian for now; English is in development. This guide uses the English names the buttons will have — the layout is the same, so each step is easy to follow in either language.

02 Workspace

Microkoi keeps everything about a project in a workspace folder: requests, environments, mocks, notes and captured traffic. The first launch opens the welcome screen.

The handiest setup is a folder inside your project repository: collections, environments, mocks, mock servers, monitors and notes go to git, while the traffic database is excluded automatically.

The same actions are in the File menu, along with a submenu of recent workspaces and Close workspace (⌘⇧W). A workspace opened on this computer for the first time shows a bar with a Trust button: until then its mock servers and monitors do not start on their own.

03 Starting the proxy

Open the Traffic section and click Start. The proxy comes up on 127.0.0.1, port 9090 — you can change the port in settings. To start it automatically, turn on “Start when a workspace opens” in settings.

All traffic on your computer

Remember to turn the system proxy off when you are done: while Microkoi is not running, programs routed through it cannot reach the network.

A single program

Many command-line tools and development environments read the proxy address from environment variables. Set them in the terminal before starting the program:

export HTTP_PROXY=http://127.0.0.1:9090
export HTTPS_PROXY=http://127.0.0.1:9090

For programs with their own list of trusted certificates, point them at the Microkoi certificate file explicitly. For example, with curl:

curl --proxy http://127.0.0.1:9090 \
  --cacert "$HOME/Library/Application Support/Microkoi/Certificates/microkoi-ca.pem" \
  https://api.example.com/v1/users/me

04 Root certificate for HTTPS

To see inside secure connections you need a root certificate. Microkoi generates one the first time the proxy is used, and it is unique to your installation. Until it is installed, HTTPS requests are shown only by host, time and size.

1. On the traffic screen, click Install certificate.
2. Confirm the way your system asks: a password, a confirmation dialog or administrator rights.
3. The Microkoi Root CA certificate lands in the trusted certificate store, and programs start trusting it.

On Linux, Microkoi also adds the certificate to the browser store in ~/.pki/nssdb when certutil from libnss3-tools is available. If you need system-wide trust — for services running as another user, for example — the app shows a ready-made terminal command and a button to verify the result.

You can remove the certificate in Settings → Root certificate: the Remove button takes it out of the system store. Microkoi always fully verifies connections to real servers — there is no “trust everything” mode.

05 Phones, tablets and emulators

The Device button on the traffic screen opens step-by-step setup. The device sends its traffic to Microkoi over Wi-Fi, and exchanges appear in the same list.

1. Turn on network connections in the dialog or in the proxy settings. While they are allowed, the proxy is marked “on network” on the traffic screen.
2. In the phone’s Wi-Fi settings, set a manual proxy: your computer’s network address and the port from the dialog — both can be copied.
3. Scan the QR code or open http://microkoi.cert on the phone: the page has the certificate and instructions for iOS and Android.
4. Install the certificate and turn on trust for it in the phone’s settings. The Microkoi dialog shows when the device connects.

The proxy has no authentication, so any device on the network can use it. Turn on network connections only on a trusted network and only while debugging, and remove the certificate from the phone afterwards.

• The Android emulator reaches your computer at 10.0.2.2.
• The iOS simulator uses your computer’s own network settings.
• On Android, apps trust a user-installed certificate only if network_security_config in their debug build allows it.

06 Capture filter

The funnel button on the traffic toolbar opens the current workspace’s filter. A host outside the filter is never decrypted: the connection goes through an opaque tunnel and exchanges are not stored. That way banking, mail and apps with certificate pinning keep working while you debug.

• api.example.com — this host only
• *.example.com — the domain itself and all its subdomains
• Paste a full URL: https://api.example.com/v1/users becomes api.example.com

07 Inspecting captured traffic

• Search covers the URL, headers and text bodies of requests and responses; filters work by status class from 2xx to 5xx.
• The pause button freezes the list while new exchanges wait in a buffer, with their count on the button.
• Clicking a branch of the endpoint tree filters the list; clicking again clears the filter.
• The exchange panel shows request and response side by side. Double-click its edge to expand it; Esc restores the normal height and then closes it.
• Copy a response body with one click, or save it to a file through the system dialog — in full, even when only the beginning is shown.
• The cURL button copies a captured request as a terminal command.

08 Breakpoints

A breakpoint holds an exchange: the request before it goes to the server, the response before it reaches your app. While it is held, you can edit it.

1. Click Breakpoint in the exchange panel — a breakpoint is set on that method, host and path, for both request and response. Or add a rule in the Breakpoints list.
2. Repeat the action in your app. When the exchange stops, an editor opens over the screen.
3. Edit the method, URL, headers and body of the request, or the status, headers and body of the response.
4. Click Continue (⌘Enter), Continue unchanged, or Abort — then your app gets a 502.

An exchange waits for a decision for at most 10 minutes, then continues unchanged. The master switch turns off every breakpoint and releases everything that is held.

09 Your first request in the API client

1. In the Requests section, click “+” on the tab bar.
2. Choose a method and type the URL. The scheme is optional: external hosts use HTTPS, localhost uses HTTP.
3. Fill in params, headers, body and auth on the editor tabs.
4. Press ⌘↩ to send; press it again to cancel.
5. Press ⌘S to save the request to a collection.

Any captured exchange opens in the client with the “To requests” button, and a whole branch of the endpoint tree can be saved as a collection with the button that appears on hover.

Paste a cURL command straight into the URL bar and the tab fills in with method, URL, headers and body. “Import cURL” opens a command in a new tab, and “Copy cURL” builds a command from the request with the active environment’s variables filled in.

10 Environments and variables

An environment is a named set of variables. Create one in the Environments editor and pick it on the tab bar. {{name}} is substituted into the URL, params, headers, body and auth, and variables can reference each other.

baseUrl   = {{scheme}}://{{host}}
scheme    = https
host      = api.example.com

GET {{baseUrl}}/v1/orders?requestId={{$uuid}}

The “secret” flag hides a value in the interface but does not encrypt it on disk. If the environment is in your repository, the value goes to git with it.

11 Mocks

1. Select an exchange on the traffic screen and click “Make mock” — or click “+” in the Mocks section.
2. Check the method, host and path. A mock made from traffic starts disabled.
3. Set the status, delay, headers and body, then save with ⌘S.
4. Enable the mock with its toggle. Replaced exchanges are marked in traffic.

When several mocks match, the most specific one wins: a literal path beats a wildcard, and a set host or method beats “any”. Mocks only work for hosts captured by the workspace filter.

12 Mock servers

A mock server is a separate API on its own port that your app calls directly, like a backend. Unlike a mock, it works without the proxy.

1. Hover a host or path branch in the traffic tree and click “Create mock server from branch” — or click “+” in the Mock servers section.
2. Review the endpoints: each method and path became an endpoint with the last captured response.
3. Turn on the Running toggle. The server starts on a free port from 9091 up.
4. Point your app at the server, for example http://127.0.0.1:9091, instead of the real API.

• HTTPS works on the same port: the device must trust the Microkoi root certificate.
• For a phone, turn on “Local network access” and use your computer’s network address.
• A request with no matching endpoint gets a 404, and in the Log tab such a request has a “Create endpoint” button.

13 Monitoring

1. Click the monitoring icon on a request or folder in the collection tree, “To monitoring” in the request editor, or “Monitoring” in the exchange panel.
2. Set the interval — from 20 seconds to a day — and success conditions: status code, a value at a JSON path, text in the body or a header.
3. While the app is open, the monitor checks itself. You get a system notification when it goes down and when it recovers.

“Check all” and the check button on a folder poll many monitors at once — handy after a deploy. A failed check has an Exchange button that opens the full request and response.

14 Notes

In the Notes section, the Note and Folder buttons create items at the root, and the buttons that appear when you hover a folder create them inside it. Notes are plain .md files in the notes folder and save themselves.

15 Troubleshooting