> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nerdit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Networking and HTTPS

> Choose local, LAN, hosted, or domain access and understand their security boundaries.

## Choose an access path

| Access                   | Requirements                                                          | Audience                                                  |
| ------------------------ | --------------------------------------------------------------------- | --------------------------------------------------------- |
| Application loopback URL | Running application                                                   | Processes on the Engine machine.                          |
| Local or LAN HTTPS       | Enabled Caddy proxy, resolvable hostname, trusted internal CA         | Clients that can reach the machine and trust its CA.      |
| Your own domain          | DNS and network routing to the machine; internal CA or opt-in ACME    | Clients that can reach that domain.                       |
| Hosted share             | Linked Engine, working cloud connection, suitable account entitlement | Private owner access or explicitly enabled public access. |

API access and application access are separate. Enabling an application proxy does not authenticate your application users, and an Engine API token does not automatically protect an application's URL.

## Enable local HTTPS

Released installations already include Caddy. Source installations need a compatible Caddy executable on `PATH` or configured as `[proxy].caddy_binary`.

Choose a hostname your clients can resolve to the Engine machine. This example uses `nerdit.lan`; replace it with your own name:

```bash theme={null}
nerdit config set proxy enabled=true hostname_override=nerdit.lan --dry-run
nerdit config set proxy enabled=true hostname_override=nerdit.lan
nerdit daemon restart
nerdit proxy status
nerdit routes
```

All proxy settings require an Engine restart. The default HTTPS port is 443. A Linux system installation grants the Caddy child permission to bind privileged ports. A Linux user installation must either use an unprivileged port such as 8443 or separately grant the bundled Caddy permission; file capabilities must be reapplied after upgrades. macOS does not use Linux `setcap`.

```bash theme={null}
nerdit config set proxy https_port=8443
nerdit daemon restart
```

Use the resulting URL including its port. `public_port` only changes advertised URLs; it does not forward traffic or change the listener. Keep the Caddy admin endpoint on loopback. If another Caddy owns port 2019, select a different `[proxy].admin_addr` instead of overwriting that server.

## Trust the internal certificate authority

```bash theme={null}
nerdit trust
```

The CLI shows the CA fingerprint and asks for confirmation. On each client machine, verify the fingerprint through a trusted channel before trusting a remote Engine. To save the verified root certificate without installing it:

```bash theme={null}
nerdit trust --output root.crt
```

Use `nerdit untrust` when removing trust. Do not make `curl -k` or disabled browser certificate validation part of normal operation. Internal certificates are not publicly trusted; sending someone a LAN URL does not install your CA on their device.

## Path routing and subdomains

Path mode gives applications URLs such as `https://nerdit.lan/my-app/`. Applications must work under a path prefix: hard-coded `/assets`, root redirects, and absolute callback URLs may need changes.

For applications that need a hostname root, configure subdomain mode:

```bash theme={null}
nerdit config set proxy mode=subdomain base_domain=apps.example.com --dry-run
nerdit config set proxy mode=subdomain base_domain=apps.example.com
nerdit daemon restart
```

Replace `apps.example.com` with a domain you control and point its application subdomains at the Engine. Nerdit does not provision DNS. Local mDNS can help with the machine's `.local` hostname but does not provide wildcard subdomain DNS, and multicast may not cross WSL, guest Wi-Fi, VLAN, or VPN boundaries.

## Use your own domain

Point a domain at the Engine machine, enable the proxy, and associate it with an application:

```bash theme={null}
nerdit domains add my-app app.example.com
nerdit domains list my-app
```

Without ACME, the domain uses the Engine's internal CA. A stored domain can be `withheld` until the application is routed; check route readiness and certificate state separately.

For a publicly trusted certificate, provide real public DNS and inbound ports 80 and 443, then apply a configuration file:

```toml acme.toml theme={null}
[proxy.acme]
enabled = true
email = "operator@example.com"
```

Replace the email with your operational contact. Apply it through the [configuration workflow](/engine/configuration#apply-a-configuration-file), restart the Engine, and request the certificate as an admin:

```bash theme={null}
nerdit domains add my-app app.example.com --acme
nerdit domains list my-app
nerdit doctor
```

HTTP-01 validation must reach public port 80. A custom internal HTTP port only works if external port 80 is forwarded to it. Check the `acme_http_port` diagnostic, firewall, DNS, and proxy logs if issuance remains pending. A pending public certificate does not fall back to the internal CA; `nerdit trust` cannot fix it. Back up [certificate and ACME account state](/engine/backup-recovery) before recovery.

```bash theme={null}
nerdit domains remove my-app app.example.com
```

Domain removal stops that route, not the underlying application.

## Hosted sharing

Connect the Engine through the [App](/app/) before creating a hosted URL:

```bash theme={null}
nerdit share my-app
nerdit share my-app --show
nerdit unshare my-app
```

The default share is private. Public sharing requires the appropriate account entitlement and an explicit exposure acknowledgment or configured edge authentication:

```bash theme={null}
nerdit share my-app --public --consent
```

<Warning>
  A public share can be opened by anyone with its URL. Check the application's own authentication and data before enabling it. A hosted share depends on the cloud connection; local applications and locally routed domains can continue independently.
</Warning>

## Add basic authentication at the proxy

Store a password in the application's secret scope, then reference it in `nerdit.toml`:

```toml theme={null}
[deploy.edge_auth]
user = "operator"
password = "${secrets.APP_PASSWORD}"
```

See [secret handling](/engine/security#application-secrets) before setting the value. An unresolved edge-auth secret withholds the protected proxy route rather than opening it. This protects proxy access; direct loopback access and your application's authorization remain separate boundaries.