> For the complete documentation index, see [llms.txt](https://docs.stoobly.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stoobly.com/guides/proxy-configuration/forward-proxy/enable-https-traffic.md).

# Enable HTTPS Traffic

{% hint style="info" %}
The following is only required if both:

* The proxy is configured as a forward proxy
* Recording HTTPS traffic is desired
  {% endhint %}

To enable recording HTTPS traffic, we first must trust Stoobly agent to be a certificate authority. To do so, you will need to add the CA certificate generated by Stoobly as a trusted certificate authority.

## System Wide Configuration

{% hint style="info" %}
Some applications (e.g. browsers) will require additional specific configuration. Please refer to their documentation.
{% endhint %}

### Automated Setup

{% tabs %}
{% tab title="Mac" %}
In the terminal run the following command:

```
stoobly-agent ca-cert install
```

This installs the CA certificate under **System** in **Keychain Access**. To find the certificate file path, use:

```bash
stoobly-agent ca-cert show --format cer
```

{% endtab %}

{% tab title="Linux" %}
In the terminal run the following command:

```
stoobly-agent ca-cert install
```

This will run Linux distribution specific commands to install the CA cert. We currently support the following distributions:

* Debian based ones, such as Ubuntu
* RHEL based ones, such as CentOS
  {% endtab %}
  {% endtabs %}

### Manual Setup

{% tabs %}
{% tab title="Mac" %}

1. Get the certificate path:

   ```bash
   stoobly-agent ca-cert show --format cer
   ```

   This outputs the path to the certificate file (e.g. `~/.stoobly/ca_certs/mitmproxy-ca-cert.cer`).
2. Open **Keychain Access** and click the **+** button in the top left corner
3. Select the certificate file using the path from step 1
4. Double-click the newly added row **mitmproxy**
5. Click the dropdown next to **When using this certificate**, and select **Always Trust**
   {% endtab %}

{% tab title="Linux" %}

1. Get the certificate path:

   ```bash
   stoobly-agent ca-cert show --format pem
   ```

   This outputs the path to the certificate file (typically `~/.stoobly/ca_certs/mitmproxy-ca-cert.pem`).
2. Install the certificate for your Linux distribution using the certificate path from step 1:

   For Debian/Ubuntu-based distributions:

   ```bash
   sudo cp $(stoobly-agent ca-cert show --format pem) /usr/local/share/ca-certificates/mitmproxy-ca-cert.crt
   sudo update-ca-certificates
   ```

   For RHEL/CentOS-based distributions:

   ```bash
   sudo cp $(stoobly-agent ca-cert show --format pem) /etc/pki/ca-trust/source/anchors/mitmproxy-ca-cert.crt
   sudo update-ca-trust
   ```

{% endtab %}
{% endtabs %}

## Browser Configuration

Most browsers use the system certificate store, so after running `stoobly-agent ca-cert install`, Chrome, Edge, and Safari should automatically trust the CA certificate. Firefox uses its own certificate store and requires manual configuration.

{% tabs %}
{% tab title="Chrome / Edge" %}
Chrome and Edge use the system certificate store. After installing the CA certificate system-wide with `stoobly-agent ca-cert install`, these browsers should automatically trust it.

**Verification:**

1. Start Stoobly agent: `stoobly-agent run`
2. Configure your browser to use the proxy (see [Forward Proxy configuration](/guides/proxy-configuration.md))
3. Visit an HTTPS site (e.g., `https://example.com`)
4. If no certificate warning appears, the CA certificate is properly trusted

**If you see certificate warnings:**

* Ensure you ran `stoobly-agent ca-cert install` with administrator privileges
* Restart your browser after installing the certificate
* On macOS, verify the certificate is trusted in Keychain Access
  {% endtab %}

{% tab title="Firefox" %}
Firefox uses its own certificate store and requires manual import of the CA certificate.

1. Get the certificate path:

   ```bash
   stoobly-agent ca-cert show --format pem
   ```

   This outputs the path to the certificate file (typically `~/.stoobly/ca_certs/mitmproxy-ca-cert.pem`).
2. Open Firefox and navigate to certificate settings:
   * Go to **Settings** (or **Preferences**)
   * Search for "certificates" in the search bar
   * Click **View Certificates** under **Certificates**
3. Import the certificate:
   * Click the **Authorities** tab
   * Click **Import...**
   * Navigate to the certificate path from step 1 (use the full path)
   * Select the certificate file and click **Open**
4. Trust the certificate:
   * In the dialog that appears, check **Trust this CA to identify websites**
   * Click **OK**
5. Verify:
   * Start Stoobly agent: `stoobly-agent run`
   * Configure Firefox to use the proxy
   * Visit `https://example.com` - you should see no certificate warning

**Note:** You can also use `--format cer` if you prefer the `.cer` format:

```bash
stoobly-agent ca-cert show --format cer
```

{% endtab %}

{% tab title="Safari" %}
Safari uses the macOS system Keychain. After running `stoobly-agent ca-cert install`, Safari should automatically trust the certificate.

**Verification:**

1. Verify the certificate is installed in Keychain Access:
   * Open **Keychain Access**
   * Search for "mitmproxy" or "stoobly"
   * Ensure it shows **Trust** as "Always Trust"
2. If not trusted:
   * Double-click the certificate
   * Expand **Trust**
   * Set **When using this certificate** to **Always Trust**
   * Close the dialog
3. Restart Safari and test with an HTTPS site through the proxy
   {% endtab %}
   {% endtabs %}