Network, Proxy, and Updates

Cola needs cloud services for login, account-state refresh, model calls, payment, and automatic updates. Network issues usually appear as login failures, unavailable models, tasks failing immediately, or failed update checks.

Responsible Use Boundary

Use Cola only in environments that comply with laws, service terms, and your organization's network-security requirements.

Cola's network and proxy settings are for networks you are allowed to use, such as an organization-provided proxy, school or enterprise gateway, home network equipment, or a security access policy explicitly required by your organization.

Do not use Cola's proxy settings to bypass laws, platform rules, regional restrictions, or organizational network policies. These docs do not provide instructions for that.

Features That Need Network Access

These features need a stable network:

• Cola account login and email verification codes.
• Google or third-party OAuth authorization.
• Model lists, model tiers, and account quota refresh.
• Agent chats and model gateway requests.
• Top-ups, subscriptions, and order status refresh.
• Automatic update checks and installer downloads.

Speech recognition itself runs locally, but the task after transcription may still need network access for models or cloud services.

Basic Checks First

When you see a network-related issue, check in this order:

1. Confirm that the current network can open common websites.
2. Confirm that system time and time zone are correct. A large time difference can break login or certificate checks.
3. Quit Cola completely and reopen it.
4. If you are on a company, school, or managed network, confirm that desktop apps are allowed to access external services.
5. If you use a proxy or security gateway, confirm the host, port, authentication, and access policy are still valid.

If only Cola fails while the browser can open websites, run Cola's built-in Network Diagnostics first.

Run Network Diagnostics

Open Settings > About > Network Diagnostics and click Run diagnostics.

Diagnostics check Cola's current network path, proxy reachability, and key service connections. Results may include:

• Pass: the checked service is reachable.
• Proxy endpoint unreachable: the proxy host or port did not accept a connection.
• Some services unavailable: only some Cola services failed.
• Server diagnostics skipped: the local Cola Server is not connected yet. Restart the app first.

If you need to report the issue to support, copy the diagnostics result. Before sending it, check for hostnames, accounts, paths, or organization network details you do not want to share.

Configure Cola App Proxy

If your network requires desktop apps to reach external services through a specific proxy, enable proxy in Settings > About > Network Proxy.

Cola supports:

• HTTP
• SOCKS5

When filling it out:

• Server should contain only the hostname or IP, without http:// or socks5://.
• Port must be a number from 1 to 65535.
• If the proxy requires authentication, enter username and password.
• Bypass is for local addresses such as localhost and 127.0.0.1 that should connect directly.

After saving, new requests use the proxy immediately. Existing long-lived connections may need to reconnect. Run Network Diagnostics again after changes to confirm the result.

IPv4 and IPv6

Cola's outbound connections use IPv4 only by default. Plenty of home and office networks advertise IPv6 addresses that don't actually route, and every connection has to wait for that attempt to fail first — which is what makes sign-in and model calls feel slow.

If your network is IPv6-only, or you know IPv6 works and want automatic selection back, set the COLA_NET_IP_FAMILY environment variable:

• Unset, 4, or an unrecognized value: IPv4 only (the default).
• 6: IPv6 only.
• auto: back to automatic selection, trying both.

The value is read once when the process starts, so you have to restart Cola for a change to apply — quit the desktop app completely and open it again.

It governs only the connections Cola makes itself. Web pages inside the app, the embedded browser, and the auto-updater use the system network stack and are unaffected. Behind a proxy, it governs Cola's hop to the proxy; the proxy resolves the final destination itself.

Company or School Networks

If you use Cola on a managed network, ask your network administrator:

• Whether Cola can access login, model, and update services.
• Whether a specific proxy or security gateway is required.
• Whether certificate inspection, endpoint security software, or firewall policy affects desktop apps.
• Whether third-party OAuth login pages and payment pages are allowed.

Do not send internal proxy accounts, certificates, access tokens, or screenshots of security policies to Cola. When reporting an issue, prefer the Network Diagnostics summary and the time the issue occurred.

Required Updates

When a downloaded update changes the major or minor version number (for example, upgrading from 1.2.x to 1.3.x), the update dialog cannot be closed or skipped — the update must be installed before you can continue. Patch-level updates (for example, 1.3.0 to 1.3.1) can still be postponed. Cola waits until no session is actively answering before showing a required update prompt.

Automatic Update Failed

Automatic update needs access to Cola's update service and installer download. If updates fail, check:

• Whether the network is stable.
• Whether the proxy or security gateway allows access to the update service.
• Whether disk space is sufficient.
• Whether Cola has permission to write to the location needed for the update.
• Whether multiple Cola versions are running at the same time.

When the in-app update cannot go through, Cola shows an Update ran into a problem dialog saying a manual install is needed: Download Installer downloads the package this computer needs (the dmg on macOS, the exe on Windows) — quit Cola once it is downloaded, then install over the current app. Later just closes the dialog. The same Download Installer button also appears under Settings > About and in the Cola menu.

Prefer the package behind that button over hunting on the website: it is exactly the build this computer was offered. Only when Cola cannot tell which package applies does the button open the website instead.

Do not install unknown packages, and do not run system commands from unfamiliar pages.

Common Symptoms

Login page does not open Check whether the browser is blocked by macOS or organization policy. Start login again from Cola. Do not send passwords, verification codes, or authorization URLs to Cola.

Cola still shows signed out after successful login Reopen Cola and confirm that system time is correct. If it happens repeatedly, run Network Diagnostics and report the time.

Model unavailable or task fails immediately First read Account, Usage, and Models to confirm account, credits, and model tier are valid. If those are fine, check Network Diagnostics.

Certificate or security software errors On company or school networks, certificate checks may be controlled by organization policy. Contact the network administrator. Do not disable system security protections on your own.

What to Provide When Reporting

For network issues, provide:

• The exact time the issue happened.
• The Cola version you are using.
• What you were doing, such as login, model call, or update.
• The Network Diagnostics summary.
• Logs or screenshots from the relevant time window.

Logs and diagnostics may contain network environment details, paths, or task snippets. Remove sensitive information before sending.