DOCKER & HEADLESS
Run Antigravity Manager with Docker or Headless Mode
Run Antigravity Manager on a NAS, Linux server or Docker Desktop, manage accounts in your browser, and connect your AI clients to its API. This setup keeps data in a host folder and uses port 8045 for both the service and the OAuth callback.
For Antigravity Tools 5.0.0 · Updated
What do you need to run the Docker image?
You need Docker Engine with Compose, an amd64 or arm64 host, and a writable folder for application data. Run the commands on the Docker host; with Docker Desktop, use a folder shared with its Linux containers.
- Software: check
docker version,docker compose versionandpython3 --version. Python 3 generates the private credentials below; on Windows, usepy. Use a current Docker release: Docker documents a loopback publishing issue before Engine 28.0.0. - Storage: create a dedicated deployment folder. Keep
compose.yml,.envanddata/together; reserve additional space for backups and logs. - Account: have an account you can authorize and an outbound connection to its authentication and model services.
The container includes the Web UI and runs in headless mode. You manage it through a browser. For switching the IDE account on your own computer, use the desktop installation.
Create the data folder and two credentials
Generate a separate management password and API key before starting the container. The management password opens the Web UI; the API key connects model clients.
In your new deployment folder, save the following as prepare_env.py. Run python3 prepare_env.py on Linux or macOS, or py prepare_env.py on Windows.
from pathlib import Path
import os
import platform
import secrets
architecture = {
"x86_64": "amd64", "amd64": "amd64",
"aarch64": "arm64", "arm64": "arm64",
}.get(platform.machine().lower())
if architecture is None:
raise SystemExit("Choose a Docker host with an amd64 or arm64 CPU.")
content = (
"AG_API_KEY=" + secrets.token_urlsafe(36) + "\n"
"AG_WEB_PASSWORD=" + secrets.token_urlsafe(36) + "\n"
"AG_PLATFORM=linux/" + architecture + "\n"
"AG_HOST_PORT=8045\n"
)
try:
fd = os.open(".env", os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
except FileExistsError:
raise SystemExit(".env already exists. Keep or edit it; credentials were unchanged.")
with os.fdopen(fd, "w", encoding="utf-8") as output:
output.write(content)
Path("data").mkdir(mode=0o700, exist_ok=True)
print("Created .env and data/. Open .env privately to read your credentials.")
The script creates .env and data/, detects the local CPU architecture, and refuses to overwrite an existing credentials file. Open .env privately when you need either value. Keep it out of source control; on Windows, restrict access using the folder’s security settings.
If you prepared the files on a different machine, set AG_PLATFORM to the Docker host’s architecture: linux/amd64 or linux/arm64. Keep AG_HOST_PORT=8045 for the simplest OAuth setup. See port conflicts and remote OAuth before choosing another port.
Save the configuration as compose.yml
Save this file beside .env and data/. It pins version 5.0.0 and its image digest, publishes port 8045 locally, and mounts the data folder into the container.
services:
manager:
image: lbjlaq/antigravity-manager:v5.0.0@sha256:a268667fe0603d39c1246179d47f085e810ce0ba81e6c17a3b8edb0ba37a5870
platform: ${AG_PLATFORM:-linux/amd64}
ports:
- "127.0.0.1:${AG_HOST_PORT:-8045}:8045"
environment:
PORT: "8045"
ABV_BIND_LOCAL_ONLY: "false"
ABV_DATA_DIR: /root/.antigravity_tools
API_KEY: ${AG_API_KEY:?Set a private AG_API_KEY}
WEB_PASSWORD: ${AG_WEB_PASSWORD:?Set a separate AG_WEB_PASSWORD}
RUST_LOG: info
volumes:
- type: bind
source: ./data
target: /root/.antigravity_tools
bind:
create_host_path: false
restart: unless-stopped
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
| Setting | What it controls |
|---|---|
| 127.0.0.1:8045:8045 | Connects port 8045 on the Docker host to port 8045 in the container. Remote access uses a tunnel. |
| ABV_BIND_LOCAL_ONLY=false | Allows Docker’s bridge network to reach the application inside the container. Host access stays limited by the port mapping. |
| API_KEY / WEB_PASSWORD | Supplies the API credential and Web UI password from the corresponding AG_ values in .env. |
| ABV_DATA_DIR + bind mount | Stores accounts, settings and databases in the host’s data folder. A missing source folder produces an error instead of silently creating a new one. |
| restart / logging | Restarts after an unexpected exit and rotates Docker stdout/stderr logs at 10 MB, keeping up to three files. Application logs in data/ need their own retention. |
The :? expressions require nonempty credentials. Docker administrators can inspect container environment variables, so limit access to the Docker daemon as well as the deployment folder.
Start the service and connect a client
Validate the configuration, download the pinned image, and start the service from the deployment folder. Run each command after the previous one succeeds.
docker compose -p ag-stable config --quiet
docker compose -p ag-stable pull
docker compose -p ag-stable up -d
docker compose -p ag-stable psconfig --quiet checks the configuration without printing the expanded credentials. If Compose reports a missing value, fill it in before continuing.
- Open the Web UI. On the Docker host, go to
http://localhost:8045. For a remote host, first open the SSH tunnel below. - Sign in. Enter
AG_WEB_PASSWORDfrom.env. - Add an account. Open Accounts → Add Account → Start OAuth, finish authorization in the new tab, then check that the account appears in Accounts. Refresh the list if necessary.
- Check the proxy. Open API Proxy. If it is stopped, start it and confirm Service Running.
- Connect your client. An OpenAI-compatible client on the same computer uses
http://127.0.0.1:8045/v1andAG_API_KEY. For Claude Code and other clients, follow the client-specific settings.
Check proxy status with curl --include http://127.0.0.1:8045/healthz (PowerShell: curl.exe). Then send a short model request using a model from your instance’s catalog. Check that the response contains an answer before connecting a larger workflow.
The Web UI and API share container port 8045. Management routes use /api; client routes depend on the protocol. Keep the container’s PORT setting at 8045 when following this guide.
Complete OAuth on a remote server
Forward your laptop’s local port 8045 to the server before starting OAuth. Version 5.0.0 normally redirects the browser to http://localhost:8045/auth/callback, so the browser needs a route from that local address to Manager.
Run this command on the computer where you will open the browser. Replace USER@SERVER with your SSH login:
ssh -N -o ExitOnForwardFailure=yes -L 127.0.0.1:8045:127.0.0.1:8045 USER@SERVER- Keep the SSH session open. The command normally stays in the foreground without a prompt.
- Open
http://localhost:8045in your browser, sign in and start OAuth from Add Account. - Complete consent in the new tab. Return to Accounts and confirm the saved account.
Clients running on that laptop can also use the forwarded port while the tunnel is open. Each additional computer needs its own reachable connection to Manager.
If port 8045 is already occupied
For a conflict on the server, set AG_HOST_PORT=18045 in .env and recreate the service. Change only the tunnel’s destination to -L 127.0.0.1:8045:127.0.0.1:18045; keep local port 8045 for the callback.
For a conflict on the browser computer, stop the application using local port 8045 or use the manual callback flow below. The SSH option ExitOnForwardFailure=yes makes a bind failure visible immediately.
Use a different local port and submit the callback manually
Open the service through a reachable port, such as a tunnel using -L 127.0.0.1:18045:127.0.0.1:8045, then browse to http://localhost:18045. Start OAuth and keep the Add Account dialog open.
If the final redirect to localhost:8045 cannot reach Manager, copy that tab’s full callback URL. Paste it into Paste callback URL or code... in the original dialog and submit it. Confirm the account appears after processing. Keep the URL private because it contains the authorization code.
For a custom HTTPS callback, ABV_PUBLIC_URL sets the base URL before /auth/callback is appended. Use it only with a reachable callback route and an OAuth client that accepts that redirect URI. The SSH setup works with the default local callback.
Choose network access for your clients
Keep loopback publishing and an SSH tunnel for personal access. For shared access, configure a private network or HTTPS reverse proxy, authenticate clients, and restrict who can reach the management interface; see the security guide.
Bridge networking is used by this Compose file. Leave ABV_BIND_LOCAL_ONLY=false so Docker can reach the container’s listener. If you deliberately switch to host networking, remove ports and review the application’s bind address: the process then uses the host’s network directly.
For IPv6-only access, check the published host address, the Docker bridge and the route from your client. Docker can forward a host IPv6 port to an IPv4-only container under supported userland-proxy settings. The exact behavior depends on the daemon configuration; this example binds only IPv4 loopback. Use Docker’s port-publishing documentation when changing it.
To diagnose a configured IPv6 endpoint, use an IPv6-capable client, curl -6, and brackets around a literal IPv6 address in the URL. Check host and cloud firewall rules if the connection times out. Once HTTP responds, continue with authentication and a short model request.
Keep accounts and settings across recreation
Keep the same host data/ folder when recreating the container. Compose resolves ./data beside compose.yml and mounts it at /root/.antigravity_tools, matching ABV_DATA_DIR.
After adding your account, save a visible setting such as the theme. Run the following from the same deployment folder, then sign in again and check the setting, account list and proxy status:
docker compose -p ag-stable up -d --force-recreate manager
docker compose -p ag-stable psIf Accounts is empty afterward, inspect the mounted source path before adding accounts again. Moving compose.yml without its data folder, or selecting a different Docker host, can point the deployment at different storage.
Fix “permission denied” on a NAS or Linux host
Check the data folder’s owner and NAS access rules, then run docker compose -p ag-stable exec manager id to see the container user. The published image runs as root by default; rootless Docker and NAS permissions can still restrict host writes. Grant access to the dedicated data folder using your platform’s ownership or ACL settings.
On SELinux systems, check the denial and the folder label. A private Z label may be needed for a dedicated bind mount; apply it only to that application folder. Docker Desktop users should check file sharing. See Docker’s bind-mount instructions for these host-specific settings.
Back up, update and restore the deployment
Back up the complete data folder together with the current Compose file and credentials before changing versions. Stop Manager while archiving data so its database files are copied consistently.
On Linux or macOS, run this in the deployment folder with permission to read all files in data/. It creates a new private backup directory, stops the service for the archive, then starts it again.
(
set -eu
umask 077
backup_dir=$(mktemp -d "./backup-$(date -u +%Y%m%dT%H%M%SZ)-XXXXXX")
cp compose.yml .env "$backup_dir/"
docker compose -p ag-stable stop manager
if tar -czf "$backup_dir/data.tar.gz" data; then
docker compose -p ag-stable start manager
tar -tzf "$backup_dir/data.tar.gz" >/dev/null
printf 'Backup saved in %s\n' "$backup_dir"
else
docker compose -p ag-stable start manager
exit 1
fi
)
Check that the command finishes successfully and keep the reported backup directory in protected storage. On Windows, stop the service, copy the entire data folder plus compose.yml and .env to a new private backup folder, then start it again.
Install an update
- Read the target release notes and check its Docker tag and CPU architectures.
- Replace both the tag and digest in
image. Keeping the old digest keeps the old image content. - Run
docker compose -p ag-stable config --quiet, thendocker compose -p ag-stable pullanddocker compose -p ag-stable up -d. - Sign in, check your accounts and settings, and send a short request. Keep the pre-update backup until the deployment works.
Restore after a failed update
- Run
docker compose -p ag-stable downfrom the deployment folder. - Move the current
data/,compose.ymland.envinto a separate recovery folder so you retain the failed state. - Copy the saved
compose.ymland.envback. Extract the backup’sdata.tar.gzinto the deployment folder; the archive already contains the top-leveldata/directory. Preserve file ownership and permissions. - Validate, pull and start with the startup commands above. Confirm accounts, settings and a short model request.
Restore the earlier image together with its matching data backup when an update changes the storage format. Restoring a backup also restores its credentials; reconnect clients with those values or rotate them deliberately.
Run stable and beta side by side
Use separate deployment folders, data folders, credentials, Compose project names and host ports. For example, keep stable at port 8045 with -p ag-stable and beta at 18046 with -p ag-beta. Give beta its own image tag and digest. Use a copied backup for test data, and stop any conflicting local tunnel before authorizing another instance.
Change a password or API key permanently
Edit AG_WEB_PASSWORD or AG_API_KEY in .env, then recreate the container. Environment values are applied again at startup, so a password changed only in the Web UI can revert on restart.
In version 5.0.0, ABV_API_KEY takes precedence over API_KEY; ABV_WEB_PASSWORD takes precedence over WEB_PASSWORD. Stored settings are used when those environment overrides are absent. Also check for exported AG_ variables in your shell, which take precedence over Compose’s .env values.
Use native headless mode and remote clients
Run a compatible installed binary with antigravity-tools --headless to serve Manager without its desktop window. The host still needs the package dependencies, writable application storage and frontend assets for the Web UI. The Docker image bundles these and sets the frontend path for you.
The current Docker setup uses a browser directly, with no VNC desktop. When migrating from an older Xvfb or noVNC deployment, back up its data and verify the source and destination data paths before switching images.
Client sync runs on the Manager machine. If Manager runs in Docker, syncing Claude Code or OpenCode writes configuration inside that container. To use a client on your laptop, configure the laptop client with the tunnel URL and API key using the Claude Code guide or OpenCode guide.
If you deliberately run a client inside the container, persist its own configuration separately. Client directories such as /root/.claude and /root/.config sit outside the application data mount in this example.
Fix common Docker startup and connection problems
Match the symptom to the component that failed: container startup, browser access, authentication, account storage or proxy forwarding.
| Symptom | What to check next |
|---|---|
| Container exits or Web UI stays unreachable | Run docker compose -p ag-stable ps and docker compose -p ag-stable logs --tail=80 manager. Check port conflicts, architecture and data permissions. Remove credentials and account details before sharing logs. |
| Laptop cannot open the server’s address | Open the SSH tunnel and browse to localhost:8045. The example publishes on the server’s loopback address. |
| Web login rejects the API key | Use AG_WEB_PASSWORD. Reserve AG_API_KEY for model clients. |
| Client returns 401 or 403 | Check its API key, protocol and endpoint. A Web UI password entered as the model API key is rejected. Continue with connection troubleshooting if the correct key also fails. |
| Docker is healthy, but /healthz returns 503 | The image’s health check calls /health. Open API Proxy and start forwarding if stopped. An empty account pool can pause the proxy after restart; add an account and check its status. |
| OAuth ends at an unreachable localhost page | Align the tunnel with local port 8045 or submit the callback URL through Add Account. See the OAuth steps. |
| Settings disappear after recreation | Check the actual bind source and keep the same data folder. For a reverting password, edit the environment value and recreate. |
| Health works, but a model request fails | Check account authorization, available models and quota. Use model selection and authorization troubleshooting for the returned error. |
Related guides and deployment documentation
Use the account guide for imports and account management, or diagnostics to collect a focused error report.
- Antigravity Tools 5.0.0 Docker documentation — headless deployment and environment variables.
- Version 5.0.0 release notes and published Docker images — releases, tags and platforms.
- Version 5.0.0 Dockerfile — bundled assets, entrypoint and health check.
- Docker Compose startup and recreation — command options for managing the service.