Workspace URLs

With an apex route configured, a workspace named my-feature uses https://my-feature.paraspace.dev:8443 by default. You can:

• trust the local certificate authority;
• remove the port from URLs;
• use your own domain.

Trusting the certificate

para's Caddy issues each workspace a certificate from its own local CA, so browsers distrust them until that CA's root is in your trust store.

Caddy tries to install its root certificate when it first issues a certificate, prompting for your password. On macOS it uses the system keychain. If that installation fails or you dismiss the prompt, install the root manually:

caddy trust    # once per machine

That covers the system store and your host NSS db, which is enough for Firefox and natively-packaged Chrome/Chromium.

All workspaces use the host's Caddy instance and share its certificate authority. Once you trust that CA, new workspaces need no additional certificate setup.

IMPORTANT

Chrome installed via Flatpak won't see that root. It's sandboxed away from the system store, so it needs a one-time manual import into Chrome's own cert store:

1. Copy the root where the sandbox can read it (it sees ~/Downloads): cp ~/.local/share/caddy/pki/authorities/local/root.crt ~/Downloads/caddy-para-root.crt
2. Visit chrome://certificate-manager → Custom → Trusted Certificates → Import → pick it (not the read-only "operating system" group).
3. If it still errors after a reload, that's stale HSTS rather than trust. Open chrome://net-internals/#hsts, delete the hostname's security policy, and reload.

Removing the port

para's Caddy binds :8443 by default because any user can. For clean, port-less URLs (https://my-feature.paraspace.dev), move it to :443 in your user config:

para config edit    # uncomment: : "${PARA_HTTPS_PORT:=443}"

On Linux, non-root can't bind ports below 1024, so also grant the caddy binary the bind capability, and re-apply it after every caddy upgrade:

sudo setcap cap_net_bind_service=+ep "$(readlink -f "$(command -v caddy)")"

macOS allows the bind as-is, so the config change alone is enough. Then para caddy start. para doctor checks the capability and prints the exact command if it's missing.

Using your own domain

Workspaces resolve at <name>.$PARA_DOMAIN. The default paraspace.dev wildcards to 127.0.0.1, which is why it works with zero setup. To serve under your own domain instead:

1. Point a wildcard *.<your-domain> → 127.0.0.1 in your DNS.
2. Set PARA_DOMAIN in the project's env file, or in your user config if it's a personal domain you want across every project.

para doctor checks that the wildcard actually resolves to 127.0.0.1, which is the most common reason a workspace comes up but its URL doesn't load.