# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.stoobly.com/guides/proxy-configuration/forward-proxy/enable-https-traffic.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.