Network, Proxy, and Updates

Cola needs cloud services for login, account-state refresh, model calls, Cola Link, payment, and automatic updates. Network issues usually appear as login failures, unavailable models, tasks failing immediately, Cola Link send/receive failures, 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 conversations and model gateway requests.
• Cola Link contacts, messages, and file sending.
• 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 > Network > 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 > Network.

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.

Company or School Networks

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

• Whether Cola can access login, model, Cola Link, 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.

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.

If automatic update keeps failing, get a new installer from the official channel. 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, balance, and model tier are valid. If those are fine, check Network Diagnostics.

Cola Link cannot send or receive Confirm that you are signed in to Cola and that the current network allows access to Cola Link services. If file sending fails, also confirm that the file still exists locally and was not moved or deleted.

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, Cola Link, 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.