Network proxy

Fabric Agents makes outbound HTTPS calls to LLM providers, MCP servers, REST API sources, the auto-update endpoint, and the docs MCP. On a corporate network you may need to route those through an HTTP/HTTPS proxy; on a network that does TLS inspection, you'll also need to trust a corporate CA certificate.

Both knobs are first-class settings.

Proxy

Schema

{
  "networkProxy": {
    "enabled": true,
    "httpProxy":  "http://proxy.corp.example.com:8080",
    "httpsProxy": "http://proxy.corp.example.com:8080",
    "noProxy":    "localhost,127.0.0.1,.corp.example.com"
  }
}

Setting it

Configure the proxy from Settings → Network. The form writes directly to ~/.fabric-agent/config.json under the networkProxy key. You can also edit the JSON yourself — the app re-reads it on next launch.

What the proxy covers

• LLM provider requests — Anthropic, Pi-SDK providers, custom endpoints.
• MCP HTTP and SSE sources.
• REST API sources.
• Auto-update checks (Electron talks to the update URL).
• WebSocket connections for the Fabric Agents server when the desktop app connects to a remote server.

What the proxy does not cover

• Stdio MCP subprocesses. These are local IPC — no network, no proxy.
• Local endpoints (e.g. http://localhost:11434 for Ollama). Put localhost,127.0.0.1 in noProxy if your proxy would otherwise swallow them.
• Bash commands run by the agent. Whatever they do is subject to the tool's own env, not Fabric Agents' proxy config. If you need git, curl, or npm to go through the proxy, set HTTP_PROXY / HTTPS_PROXY in your shell so the subprocess inherits them.

The bypass list

noProxy accepts:

Localhost isn't bypassed by default. Add localhost,127.0.0.1,[::1] if you want local services to bypass the proxy.

Authentication

Put credentials in the proxy URL itself:

http://user:password@proxy.corp.example.com:8080

Fabric Agents doesn't have separate username/password fields for proxies. The credentials travel inside the encrypted config.json, not in plaintext.

Custom CA certificate

Corporate networks that inspect TLS install their own root certificate on your machine. Node.js (which powers Fabric Agents) doesn't automatically trust OS-level certificates — you need to point it at a PEM bundle.

The quick way — FABRIC_TLS_CA

Set the environment variable before launching:

export FABRIC_TLS_CA=/etc/ssl/corp-ca-bundle.pem

Fabric Agents forwards this to Node.js as NODE_EXTRA_CA_CERTS. Any certificate in that file joins the normal trust store.

The same way — NODE_EXTRA_CA_CERTS

If you prefer Node's own variable, that works too:

export NODE_EXTRA_CA_CERTS=/etc/ssl/corp-ca-bundle.pem

Both variables do the same thing. FABRIC_TLS_CA is the preferred name inside the app; NODE_EXTRA_CA_CERTS is the Node-native name. Setting either works.

PEM bundle format

A PEM bundle is a text file with one or more concatenated certificates, each wrapped in:

-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----

Most corporate IT teams can give you one. On macOS, you can export a certificate from Keychain Access → right-click → Export → .pem.

When you need it

• TLS errors in session logs: unable to verify the first certificate, self-signed certificate in certificate chain. That's the proxy's cert being untrusted.
• MCP servers behind corporate TLS — add the corporate CA so Fabric Agents can verify the cert the proxy presents.
• Self-hosted LLM endpoints with self-signed certs for internal-only reachability.

CLI and the remote server

For the desktop app, proxy and TLS settings live in config.json and are applied automatically. For fabric-cli and the headless server, use environment variables:

export FABRIC_TLS_CA=/etc/ssl/corp-ca-bundle.pem
export HTTPS_PROXY=http://proxy.corp.example.com:8080
export HTTP_PROXY=http://proxy.corp.example.com:8080
export NO_PROXY=localhost,127.0.0.1,.corp.example.com

fabric-cli sessions                            # uses the proxy
bun run packages/server/src/index.ts           # server also uses the proxy

The CLI also accepts --tls-ca /path/to/bundle.pem as an explicit flag, which overrides the env var for that one command.

Troubleshooting

• Requests hang on launch. Check httpsProxy is reachable from the machine. curl --proxy $httpsProxy https://www.google.com is a good smoke test.
• ECONNREFUSED to localhost services after enabling the proxy. Add localhost,127.0.0.1 to noProxy.
• unable to verify the first certificate — you need a custom CA. See above.
• Proxy authentication prompts in the app — authentication must be in the URL; there's no interactive prompt.
• The update check fails but everything else works — the Electron session needs the proxy too. Restart the app after changing networkProxy so Electron picks it up.

Related

• Environment variables — FABRIC_TLS_CA, FABRIC_SERVER_URL, and other runtime knobs.
• config.json — where the networkProxy key lives.
• fabric-cli — --tls-ca flag for ad-hoc CA overrides.