API CONNECTIONS · ANTIGRAVITY TOOLS
Antigravity Manager: Fix API Connection Errors
Start with the response your client receives. A refused connection points to the address or listener; an HTTP error gives you a route to check next. Test from the same computer, container or WSL session as the failing client.
For version 5.0.0 · Updated
Connection refused, timeout, DNS or TLS error
Open API Proxy in Manager, start the service and check its port. Run this command on the Manager computer first, then repeat it from the client’s environment using an address that reaches Manager there.
curl --noproxy '*' --include --max-time 10 http://127.0.0.1:8045/healthzReplace 8045 with your configured port. In Windows PowerShell, use curl.exe. This command connects directly, bypassing curl’s HTTP proxy settings for this request.
| Result | What to do next |
|---|---|
| 200 with health JSON | Continue with the short text request to check account access and model forwarding. |
| 401 | The HTTP listener answered. In Strict mode, health requests also require a key. Continue with the credential check. |
| 503: Proxy service is currently disabled | Start API Proxy. In 5.0.0, the process keeps listening after Stop and returns this message for /healthz and inference requests. |
| Connection refused | Check the port, service state and destination computer. If you changed the port, fully quit and reopen Manager, then repeat the check. |
| Timeout | Compare local and remote results. If local works, check the firewall, published port and client’s network address. If local also hangs, inspect Manager’s logs and running process. |
| Could not resolve host | Correct the hostname and check DNS inside the failing container or WSL session. |
| TLS or certificate error | Use HTTP for the local listener. For an HTTPS reverse proxy, check the hostname, certificate and forwarding configuration; retain certificate verification. |
If you receive an unrelated webpage, check which process owns the port. If your normal client uses an HTTP proxy, compare its routing settings with this direct test before changing the gateway configuration.
401 or 403 with token_rejected
Use the key from Manager’s API Proxy settings in your client’s API-key field. With authentication enabled in 5.0.0, a missing key produces 401; an unrecognized supplied key can produce 403 with token_rejected.
- Match the credential to the connection. AI requests use the gateway API key or an authorized user token. The Web administration login uses its configured administrator password (
WEB_PASSWORDin Docker). - Replace an old key wherever the client reads it. Check the active provider, environment variables and saved client settings. Reopen the client if it reads environment variables at startup.
- Send one credential. A direct request can use
Authorization: Bearer <API_KEY>. Manager checks non-emptyAuthorizationfirst, thenx-api-key, thenx-goog-api-key, then thekeyquery parameter. Remove stale Authorization values that mask a valid key in another header. Prefer headers to keys in URLs. - Read the rejection reason. For an issued user token, check its expiry, permitted usage times and IP limit with the gateway administrator. For a Google token-refresh error, follow the account authorization checks.
How the four authentication modes affect a test
Strict requires a key for AI routes and health checks. All Except Health leaves health checks open and protects AI routes. Off permits AI access without a key. Auto selects All Except Health when LAN access is enabled, and Off for local-only access.
Keep authentication enabled for shared access. Management routes have their own administrator authentication. See the security guide for access controls and key rotation.
Retry the same request after correcting the key. If it now reaches model selection or returns an account-access error, continue with that response.
403 with ip_blocked
Check the IP address and message in the ip_blocked response, then find the matching whitelist or blacklist entry in Manager. Correct that specific rule or its expiry for the intended client.
Containers, NAT and reverse proxies can change the address Manager sees. In 5.0.0, Manager reads the first X-Forwarded-For value, then X-Real-IP, then the TCP peer address. A reverse proxy should replace client-supplied forwarding headers, and network rules should restrict direct access to the backend. Follow the network-access setup before relying on an IP allowlist.
After the IP check passes, retry with the intended API key. Keep the previous rule value so you can restore a temporary change. For a response naming Google verification, eligibility or project access, use the account-access guide. Client integrations should use the public API paths below; Manager reserves /internal/* for direct loopback requests.
404, duplicate /v1 or the wrong endpoint
Inspect the final URL your client sends, including the path it appends to your base URL. Set the base so the version and endpoint appear once.
Append the base path to your gateway origin, such as http://127.0.0.1:8045.
Scroll the table sideways to see the complete request paths.
| Client appends | Base path | Final request path |
|---|---|---|
/chat/completions | /v1 | /v1/chat/completions |
/v1/chat/completions | Origin only | /v1/chat/completions |
/messages | /v1 | /v1/messages |
/v1/messages | Origin only | /v1/messages |
/responses | /v1 | /v1/responses |
/v1beta/models/…:generateContent | Origin only | /v1beta/models/…:generateContent |
For /v1/v1/messages, remove the extra version segment from the base. For /v1/chat/completions/responses, replace the full chat endpoint with the base expected by the Responses client. Check the request method too: a chat request uses POST; opening its URL in a browser sends GET and can return 405.
If the error names an unavailable model, choose a model supported by your gateway and account. If a reverse proxy returns its own HTML 404, check its forwarding path before editing client credentials.
Use the client settings table for your application. Claude Code and OpenCode have dedicated setup instructions, including provider selection and saved configuration.
Which address works in Docker, WSL or over LAN?
Choose the address from the client’s point of view. In an isolated container, 127.0.0.1 reaches that container. On another computer, it reaches that computer.
Manager runs in Docker
From the Docker host, use the published host port. A mapping of 18045:8045 means the host client connects to http://127.0.0.1:18045. A client on another device uses the Docker host’s reachable IP and that published port. Two services on the same user-defined Docker network can use the Manager service name and container port.
Check the actual mapping with docker ps. A port published only to 127.0.0.1 is available locally; use the Docker network guide for a tunnel or deliberate remote access.
The client runs in Docker, Manager runs on the host
On Docker Desktop, use host.docker.internal with Manager’s port. For Docker Engine on Linux, add --add-host=host.docker.internal:host-gateway when creating the client container. Manager must listen on an interface the container can reach, with authentication and firewall access configured for that connection. See Docker’s Desktop networking guide and host-gateway option.
The client runs in WSL, Manager runs on Windows
With WSL2’s default NAT networking, use the Windows host IP. Inside WSL, run ip route show default and use the address after via. Allow the connection through Windows Firewall and Manager’s LAN settings. With mirrored networking, use 127.0.0.1; check the prerequisites in Microsoft’s WSL networking guide.
For JeikCode in WSL or Docker, update the configuration used inside that environment. A sync performed by Manager on the host can leave the isolated client using a different file. The JeikCode setup explains its provider and configuration location.
Another device, IPv6 or an HTTPS reverse proxy
For another device, use the Manager host’s reachable LAN address and configured port. Enable the intended LAN listener, keep authentication on and allow only the needed network access. A private tunnel is useful when you want to keep the gateway bound locally.
For an IPv6 address, use brackets: http://[IPv6_ADDRESS]:PORT. Check the host listener, Docker port publishing and IPv6 firewall separately. With LAN access enabled, Manager 5.0.0 attempts a dual-stack listener and falls back to IPv4 if that fails. Check the startup log for the bound address, then test the published endpoint from your IPv6 client.
For HTTPS, use the hostname covered by the certificate. Configure the reverse proxy to preserve the intended API path and authentication header. For a gateway under a path prefix, adapt the client base to that prefix; the downloadable probe below expects a gateway at the origin root.
Test one request outside your client
Send a short, non-streaming text request from the same environment as the failing client. This comparison helps isolate client configuration from a problem shared by all requests through Manager.
- Start API Proxy and have an enabled account available. Copy a model ID from your installed gateway; use a model that account can access.
- Download connection-probe.py and save it locally. It uses Python 3’s standard library.
- In that folder, run
python3 connection-probe.py, orpy connection-probe.pyon Windows. - Enter your trusted gateway origin, such as
http://127.0.0.1:8045, its API key and the model ID. Enter the origin without/v1; the script adds/v1/chat/completions.
The key prompt is hidden in a normal terminal. The script connects directly, ignores system HTTP proxy settings and blocks redirects. Its 60-second socket timeout bounds waiting for network operations. Use a terminal with interactive input; review the script before running it.
View the Python request
#!/usr/bin/env python3
"""Send one direct, non-streaming request to your Antigravity Manager gateway."""
import getpass
import json
import urllib.error
import urllib.parse
import urllib.request
class NoRedirect(urllib.request.HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
def main():
root = input("Gateway origin [http://127.0.0.1:8045]: ").strip()
root = (root or "http://127.0.0.1:8045").rstrip("/")
try:
parts = urllib.parse.urlsplit(root)
valid = (
parts.scheme in ("http", "https") and parts.hostname
and not (parts.path or parts.query or parts.fragment)
and parts.username is None and parts.password is None
and parts.port != 0
and not any(c.isspace() or ord(c) < 32 for c in root)
and "?" not in root and "#" not in root
and root.isascii() and "\\" not in root
)
except ValueError:
valid = False
if not valid:
raise SystemExit("Use an origin such as http://127.0.0.1:8045, without /v1 or credentials.")
key = getpass.getpass("Gateway API key (hidden): ").strip()
if not key or any(ord(c) < 33 or ord(c) > 126 for c in key):
raise SystemExit("Enter a non-empty API key without spaces or control characters.")
model = input("Model ID from API Proxy: ").strip()
if not model:
raise SystemExit("Enter a model ID offered by your gateway.")
body = json.dumps({
"model": model, "stream": False,
"messages": [{"role": "user", "content": "Reply with Hello."}],
}).encode()
request = urllib.request.Request(
root + "/v1/chat/completions", data=body,
headers={"Authorization": "Bearer " + key, "Content-Type": "application/json"},
)
opener = urllib.request.build_opener(urllib.request.ProxyHandler({}), NoRedirect())
try:
with opener.open(request, timeout=60) as response:
status = response.status
raw = response.read(1048577)
except urllib.error.HTTPError as error:
print("HTTP", error.code)
print(error.read(65536).decode("utf-8", errors="replace").replace(key, "[redacted]"))
if 300 <= error.code < 400:
print("Redirect blocked. Verify the gateway's final origin before retrying.")
return 1
except (urllib.error.URLError, OSError, ValueError) as error:
print("Connection failed:", str(error).replace(key, "[redacted]"))
return 1
print("HTTP", status)
if len(raw) > 1048576:
print("Response exceeds 1 MiB. Inspect the gateway logs.")
return 1
text = raw.decode("utf-8", errors="replace")
print(text.replace(key, "[redacted]"))
try:
data = json.loads(text)
if not isinstance(data, dict) or data.get("error"):
raise ValueError()
content = data["choices"][0]["message"]["content"]
if not isinstance(content, str) or not content.strip():
raise ValueError()
except (ValueError, KeyError, IndexError, TypeError):
print("No text answer found. Use the response body to choose the next check.")
return 1
print("Read the answer above: does it reply to the Hello request?")
return 0
if __name__ == "__main__":
try:
raise SystemExit(main())
except (KeyboardInterrupt, EOFError):
raise SystemExit("Cancelled.")
Read the answer as well as the status. Look for a response to “Reply with Hello.” inside choices[0].message.content. If the body contains an error or an unsupported-version notice, follow that message even when HTTP is 200.
- The probe replies correctly, but your client fails: compare the provider, final URL, key and model. Then check any streaming, tool or extra reasoning fields the client adds.
- Both fail with the same response: follow the matching credential, path or upstream check on this page.
- The probe works on the host but fails in the client environment: return to the Docker, WSL or LAN address checks.
Health works, but a model request fails
Read the failed request’s body and find the same request in Manager’s logs. Health checks respond locally; a text request also needs an available account, a valid payload and access to the upstream service.
- Unsupported version: record the exact message and Manager build, including when it arrives inside HTTP 200. Follow the version compatibility checks. If the IDE works directly, keep that result as a comparison while checking the Manager request.
- thinking_budget or another field is out of range: compare with the minimal request above, then check your model and the client’s added reasoning fields. Use the request and response troubleshooting guide for the full payload check.
- 429, account cooldown or no usable accounts: check the account pool and retry timing in the limits guide.
- 503: if the body says the proxy service is disabled, start it. For capacity or upstream-unavailable messages, use the availability checks.
- Requests hang after the service was working: record the time and logs before restarting. Compare your exact build with the release notes, especially if a cooldown expires at the same time.
- Only saving a Web setting returns 400: record the failing settings action and build. Review the update guidance for that operation, then retry the same save after any change.
Do I need TUN? What about Cockpit “Test Now”?
Use a network route that covers the process making the failed request. TUN is one way to route traffic; a working direct connection or an appropriate proxy setup can also serve the application.
First establish whether the client reaches Manager. If it does, investigate Manager’s outbound connection. A proxy rule for the IDE or its language server may leave Manager or a Docker process using another route. Save the existing network settings, change one relevant rule and repeat the same request.
Cockpit’s “Test Now” runs a check in that separate extension. For a failing Manager request, use the response from your API client or the probe above. A persistent 429 goes to the limits checks; a timeout goes back to the process and network route.
Report the connection that still fails
Include the two results that narrow the problem most: the health check and the short text request, run from the failing client’s environment.
Add Manager and client versions, OS or container setup, protocol, final URL without credentials, status, error body, time and whether the request appears in Manager’s logs. Restore temporary routing and access-rule changes after comparison.
Remove keys, OAuth tokens, account identifiers, private prompts and credentials in URL query strings before sharing output. Rotate any key that was exposed.