Network configuration

Most company networks need no special setup: Syntic Code makes ordinary HTTPS requests, trusts the certificates your operating system trusts, and follows the standard proxy variables. This page covers the cases that do need attention: proxies, TLS inspection, client certificates, firewalls with allow lists, and machines that should send as little as possible.

Hosts Syntic Code contacts

Host	Used for	When
`api.syntic.ai`	Model requests, and the organization’s service-delivered settings.	Every session.
`app.syntic.ai`	Browser sign-in, the model list behind `/model`, and billing links.	Sign-in, and at session start.
The Syntic account service	Exchanging the sign-in code for a token, and the plan check after sign-in.	Sign-in, token renewal and session start.
`releases.syntic.ai`	The daily update check and `syntic update`.	Once a day, unless turned off.
Your plugin marketplaces’ hosts (for example GitHub)	Installing and refreshing plugins.	When you install, and once a day.
Hosts you configure yourself	MCP servers, `http` hooks, OpenTelemetry collectors.	Whenever they run.
Any host the agent fetches	The web fetch tool goes to the page’s own host; web search goes to a public search service.	Only when the agent uses those tools and your permissions allow it.

The account service runs on a separate host from api.syntic.ai. If your firewall only lets named hosts through, test sign-in from a machine on that network before rolling out, and add the host your firewall reports as blocked.

Model requests only go to Syntic hosts

Your sign-in credential rides on every model request, so the CLI refuses to send it anywhere unexpected. The API address must:

use https,
be exactly api.syntic.ai or app.syntic.ai (no other subdomains),
use the default port, 443,
carry no user name or password in the URL.

An apiBaseUrl setting or SYNTIC_API_BASE_URL that breaks any of these rules is refused at start, with the reason. A project’s own settings can never choose the API address. This means Syntic Code cannot be pointed at a self-hosted relay or a third-party gateway; the proxy settings below are the supported way to route traffic.

Proxies

Syntic Code reads the usual proxy variables, plus its own pair for when you want a proxy that only applies to Syntic Code:

Variable	Use
`HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY` (lower case works too)	The standard proxy settings most tools on the machine already share.
`NO_PROXY`	Hosts that bypass the standard proxy, comma separated.
`SYNTIC_HTTPS_PROXY`	A proxy for Syntic Code’s API traffic only.
`SYNTIC_NO_PROXY`	Hosts that bypass `SYNTIC_HTTPS_PROXY`, comma separated.

# A proxy for everything on this machine
export HTTPS_PROXY=http://proxy.corp.internal:3128
export NO_PROXY=localhost,127.0.0.1,.internal.example.com
 
# Or only for Syntic Code
export SYNTIC_HTTPS_PROXY=http://proxy.corp.internal:3128

A proxy that needs a user name and password can take them in the URL: http://user:pass@proxy.corp.internal:3128. Keep such a URL in the environment rather than a file you share.

Commands the agent runs, such as git, npm or curl, see the same environment, so they use your proxy too.

Certificates

The system certificate store

Syntic Code trusts the certificates installed in your operating system’s store, as well as a built-in set of public roots. If your IT team has already installed the company’s root certificate on the machine, a proxy that inspects HTTPS works with no extra setup.

Extra CA certificates

When the company root is not in the system store, point SYNTIC_EXTRA_CA_CERTS at a PEM file that holds it. The certificates in the file are added to the trusted set; the public roots stay trusted, so other HTTPS keeps working.

export SYNTIC_EXTRA_CA_CERTS=/etc/ssl/company-root.pem

If the file cannot be read, or holds no certificate, Syntic Code stops with an error that names the file, rather than failing later with an unclear handshake error.

Client certificates (mutual TLS)

If your network requires a client certificate:

Variable	Use
`SYNTIC_CLIENT_CERT`	The client certificate, as a PEM file.
`SYNTIC_CLIENT_KEY`	The matching private key, as a PEM file. Leave it unset when the key is in the certificate file.

export SYNTIC_CLIENT_CERT=~/.certs/me.pem
export SYNTIC_CLIENT_KEY=~/.certs/me-key.pem

When either file changes, the next request uses the new one, so a rotated certificate is picked up without restarting the session.

⚠️

Certificates and proxies are only accepted from places you control: your shell environment or your user settings. A repository’s .syntic/settings.json cannot set any proxy, certificate or *_PROXY variable. A hostile root certificate or proxy would let someone read your traffic, so these values are refused even in folders you trust.

Timeouts and retries

Variable	Effect	Default
`SYNTIC_API_TIMEOUT_MS`	How long to wait for a model response to start, in milliseconds (rounded up to whole seconds).	300 seconds
`SYNTIC_MAX_RETRIES`	How many times a failed or rate-limited request is retried. `0` turns retries off; the highest allowed value is 50.	3
`SYNTIC_STREAM_IDLE_TIMEOUT_SECS`	How long a streamed reply may go silent before it is abandoned and retried. `0` turns the check off.	90
`SYNTIC_ENABLE_STREAM_WATCHDOG`	Set to `0` to turn the silent-stream check off.	on

Raise the timeout and the idle limit if a proxy buffers responses or your link is slow. Blank or unreadable values are ignored.

Send less: privacy levels

On locked-down machines you can stop the optional background calls. Model requests continue; update checks, connection warm-up, the status line’s usage refresh and the daily plugin refresh stop.

Setting	Level
nothing set	`standard`: everything in the hosts table.
`SYNTIC_PRIVACY=essential`, or `SYNTIC_DISABLE_NONESSENTIAL_TRAFFIC=1`	Only the traffic a session needs.
`SYNTIC_PRIVACY=disabled`, or `SYNTIC_OFFLINE=1`	Also skips the start-up fetch of service-delivered settings, and refuses marketplace refreshes you force.

DO_NOT_TRACK=1, SYNTIC_TELEMETRY=0 and DISABLE_AUTOUPDATER=1 also move a machine to essential. syntic doctor reports the active level on its Network line. Full detail is on Data usage.

Lock down outbound traffic from commands

The settings above govern Syntic Code’s own requests. To control where the commands the agent runs may connect, use the shell sandbox and its network.allowedDomains list, and permission rules such as WebFetch(domain:example.com) for the web fetch tool. An organization can enforce both through managed settings.

To keep the web fetch tool away from certain hosts on a machine, list them in SYNTIC_WEBFETCH_BLOCKED_HOSTS (comma separated). The check happens before any request is made.

Check your setup

Run syntic doctor and read the Network line.
Run syntic auth status to confirm the credential works.
Send a one-off request: syntic -p "reply with OK".
If it fails, run it again with --debug and read the connection error.

When it goes wrong

Message or symptom	Likely cause	Fix
”TLS certificate check failed … Retrying will not help”	A proxy inspects HTTPS with a root your machine does not trust.	Set `SYNTIC_EXTRA_CA_CERTS` to the company root, or ask IT to install it in the system store.
”could not read CA certificate bundle”	The path in `SYNTIC_EXTRA_CA_CERTS` is wrong or unreadable.	Fix the path or the file’s permissions.
”host … is not a Syntic API host”	`apiBaseUrl` or `SYNTIC_API_BASE_URL` points somewhere else.	Remove the override. Use a proxy instead of a different address.
Sign-in opens the browser but never finishes	The account service host is blocked.	Allow it in your firewall, or sign in from another network.
Long replies stop part way and retry	A proxy cuts idle streams.	Raise `SYNTIC_STREAM_IDLE_TIMEOUT_SECS`, or raise the proxy’s idle limit.
Proxy variables are in `.syntic/settings.json` but ignored	Projects cannot set network variables.	Put them in your shell or `~/.syntic/settings.json`.

More fixes for sign-in problems are in Install and sign-in troubleshooting.

Feature availability Plans and models