First-Run Setup

The first time you launch Ghost, a setup wizard appears to walk you through two essential configuration steps. These steps are needed because Ghost needs special permissions to do its job — it needs to decrypt HTTPS traffic (which requires a trusted certificate) and it needs to redirect your internet traffic through itself (which requires proxy configuration).

Don’t worry — the wizard handles everything. Most users can complete setup in under 30 seconds.

Why Is Setup Needed?

When you visit a website over HTTPS (the padlock icon in your browser), the traffic between your browser and the website is encrypted. This encryption is what keeps your passwords and personal data safe from eavesdroppers. However, it also means that a traffic inspection tool like Ghost can’t read the content of those requests and responses — all it would see is encrypted gibberish.

To solve this, Ghost uses a technique called MITM (Man-in-the-Middle) interception: it generates its own security certificate, inserts itself between your browser and the website, and creates two separate encrypted connections — one between your browser and Ghost, and another between Ghost and the real website. Your browser encrypts traffic using Ghost’s certificate, Ghost decrypts it (so you can inspect it), then re-encrypts it and forwards it to the real server.

For this to work without your browser showing scary “connection not secure” warnings, your operating system needs to trust Ghost’s certificate. That’s what the first setup step does.

The second step — proxy configuration — tells your operating system to send all internet traffic through Ghost instead of directly to the internet.

Setup Wizard

1. Install CA Certificate

   When Ghost launches for the first time, it automatically generates a unique CA (Certificate Authority) certificate using ECDSA P-256 cryptography (a modern, secure algorithm). This certificate is stored in ~/.ghost/ca.crt and is unique to your machine — no two Ghost installations share the same certificate.

   Click the Install Certificate button. Ghost runs the appropriate operating system command to add the certificate to your system’s trust store:

   • On macOS: Ghost runs security add-trusted-cert to add the certificate to your login keychain (~/Library/Keychains/login.keychain-db) as a trusted SSL root. macOS will prompt for your keychain password (usually your Mac login password). Enter it and the certificate is added. This is the same process that happens when you install any corporate or development certificate.
   • On Windows: Ghost runs certutil -addstore -user Root, which adds the certificate to your user’s trusted root certificate store. This does NOT require administrator elevation (no UAC prompt) because it writes to the per-user store, not the machine-wide store.

   The wizard monitors the trust store in real-time. Once the certificate is successfully installed, a green checkmark appears next to this step. If something went wrong (you cancelled the dialog, or permissions were denied), the wizard shows what happened and lets you retry.

   Is this safe?

   Installing Ghost’s CA certificate means Ghost (and only Ghost) can decrypt your HTTPS traffic while the proxy is running. The certificate is generated locally on your machine and the private key never leaves your computer. When you stop the Ghost proxy, no interception occurs. If you uninstall Ghost, you should remove the certificate from your trust store (Ghost’s settings provide a one-click option for this).

2. Enable System Proxy

   Next, Ghost needs to know how to receive your internet traffic. There are three ways to connect, depending on what you’re testing:

   Connection Method	How It Works	Best For	Limitations
   System Proxy (recommended)	Ghost configures your operating system’s network settings to route all HTTP/HTTPS traffic through Ghost’s proxy (listening on port 4545). On macOS, this modifies the system proxy settings via networksetup. On Windows, it modifies the Registry.	Desktop browser testing, general traffic capture. This is the easiest option — once enabled, all traffic from all apps automatically flows through Ghost.	Some apps ignore system proxy settings (notably some VPN clients and certain developer tools).
   Manual Proxy	You manually configure a specific browser or application to use 127.0.0.1:4545 as its HTTP and HTTPS proxy server.	Testing a specific app while leaving all other traffic unaffected. Useful when you only want to capture traffic from one browser or one application.	Requires per-app configuration. Some apps don’t expose proxy settings.
   Mobile Device	Configure a connected mobile device (iOS Simulator, Android emulator, or physical phone) to route traffic through Ghost. This is covered in the Mobile Device Setup guide.	Mobile app testing — the primary use case for QA engineers at Hepsiburada.	Requires additional device-specific setup steps.

   System Proxy is the recommended choice for getting started. Ghost manages the proxy settings automatically:

   • On start: Ghost enables the system proxy so traffic flows through it
   • On stop: Ghost disables the system proxy so traffic goes directly to the internet again
   • On crash: The Tauri safety net detects the crash within 9 seconds and automatically disables the system proxy to restore your internet connection (see Architecture — Safety Net)

Quick Setup (One Click)

If you don’t want to go through each step individually, the wizard provides a Quick Setup button that performs everything in sequence:

1. Installs the CA certificate into your system trust store (you’ll still see the password/UAC prompt — this is required by the operating system and can’t be bypassed)
2. Enables the system proxy
3. Marks setup as complete and opens the main traffic view

This is the fastest path from “just installed Ghost” to “seeing captured traffic.”

Skipping Setup

If you want to configure things manually later (or if you’re just exploring the interface first), click Skip to dismiss the wizard. Ghost will still work for inspecting unencrypted HTTP traffic, but HTTPS traffic won’t be decrypted until the certificate is installed.

You can always come back to complete setup:

• Install the certificate: Go to the menu bar → Certificate → Install on This Mac/PC
• Enable the proxy: Click the proxy toggle button in the bottom status bar
• Re-open the setup guide: Go to View → Setup Guide in the menu bar

After Setup

Once setup is complete, Ghost shows the main traffic view — a three-panel layout with the domain scope panel on the left, the flow list in the center, and the flow inspector on the right.

Start browsing. Open any website in your browser, use any app that makes HTTP requests, or interact with a mobile app on a connected device. You’ll see every HTTP/HTTPS request and response appear in the flow list in real-time, including:

• The URL being requested
• The HTTP method (GET, POST, PUT, DELETE, etc.)
• The response status code (200 OK, 404 Not Found, 500 Internal Server Error, etc.)
• How long the request took
• How large the response was

A default session named “Default” is created automatically. All captured traffic goes into this session. You can create additional named sessions later for organizing different testing contexts (for example, “Login Flow Testing” or “Payment Regression”).

Verifying Everything Works

Check the status bar at the bottom of the Ghost window to confirm everything is running correctly:

What to Look For	What It Means	If Something’s Wrong
Green dot + “Capturing”	The proxy server is running and actively listening for traffic on port 4545	If it says “Stopped,” click the proxy toggle to start it. If it shows an error, another application may be using port 4545.
Green “SYS” badge	The system proxy is active — all traffic on your computer is being routed through Ghost	If this isn’t showing, the system proxy isn’t enabled. Click the SYS indicator in the status bar to enable it, or configure manually.
WS indicator (green)	The WebSocket connection between the frontend and backend is live, meaning real-time updates are working	If this is red or missing, the Go sidecar may have crashed. Try restarting Ghost.
Flow counter incrementing	Traffic is being captured. The number should increase as you browse the web.	If it stays at 0 even though you’re browsing, check that the proxy is running and the system proxy is enabled. Also verify the CA certificate is installed (HTTPS sites won’t work without it).

The simplest test: Open your web browser, go to any HTTPS website (like google.com), and check if the request appears in Ghost’s flow list. If it does with a 200 status code and you can see the request/response headers and body, everything is working perfectly.