Operations on AGW

Standalone and Docker

Fri, 25 Sep 2026 00:00:00 +0000

Standalone provides management pages, conversations, and scheduled jobs in one Server. It suits a local trial or a single host. Defaults use SQLite for storage and run tasks in the Server process, without a separate database service.

Use the Docker image, or build a Portable Server for your operating system and processor. Both include Web. Start with local access, then configure directory mounts and remote access as needed.

Local Docker trial

docker run -d --name agw \
 --restart unless-stopped \
 -p 127.0.0.1:30816:8080 \
 -v agw-data:/data \
 ghcr.io/zxyao145/agw:latest

Open http://localhost:30816/setup and initialize. Through a Docker port mapping, the container does not see a loopback source address, so Setup asks for the one-time Setup Code; find “Agw remote setup code” in the startup log with docker logs agw. The image includes static Web assets, so the browser connects directly to Server. latest is convenient for evaluation; use a fixed release tag for a maintained deployment.

Split Control/Data Plane deployment

Fri, 25 Sep 2026 00:00:00 +0000

Split deployment runs management and scheduling in Control Plane and task execution in Data Plane. Use it when execution environments need separate maintenance or additional nodes. For a trial on one host, Standalone is simpler to configure.

This page assumes familiarity with containers, databases, and reverse proxies. Prepare shared PostgreSQL, Data Protection keys for decrypting credentials, and workspaces accessible to every execution node. The entry proxy must support WebSocket for conversation events.

Configuration and authentication

Fri, 25 Sep 2026 00:00:00 +0000

This page covers deployment settings consumed by AGW Server and logging settings in the Host template. Configure models, Agents, Projects, and integration accounts through the management UI as described in their guides. Choose your deployment mode first, then apply changes and restart the relevant Hosts.

Start with the settings relevant to your task

For an initial local setup, keep defaults and complete initialization. Before relying on the service, locate its database and data directory and follow the backup guide.

Data, backups, and upgrades

Fri, 25 Sep 2026 00:00:00 +0000

A complete backup includes AGW configuration and records, encryption keys, and project files. Copying only the installation directory or code repository can leave out data needed to restore the service.

Locate the actual database, data directory, and Project workspaces first. Use the defaults below as a guide and confirm them against the running configuration.

What to preserve

AgwDataDir defaults to ~/agw; Docker uses /data. Paths expand ~; other relative paths resolve from the process working directory. The default SQLite database file is <AgwDataDir>/database/agw.db, or /data/database/agw.db in Docker.

Logs and troubleshooting

Fri, 25 Sep 2026 00:00:00 +0000

First locate the failing step: opening the page, signing in, calling a model, or using files and tools. Reproduce the problem with a small task so that each check narrows the cause.

Record the Server, Project, conversation, and time, then inspect the matching logs. In a split deployment, check Control Plane for management problems and Data Plane for execution problems.

Diagnostic order

Symptom	Check first
UI unavailable	Listener, port, container mapping, proxy target
Setup fails	Database connection, writable directories, remote Setup Code
Login or API Key fails	Actual Server, revoked API Key, database auth state
Third-party sign-in fails	`Auth:Oidc:PublicBaseUrl`, the callback URL registered at the provider, client credentials, Server-to-provider network
No agent response	Model Provider, model ID, credentials, pending approval/input
CLI cannot start	Execution-node executable, account, environment
Files missing	Selected root, Server path, mounts, permissions
Job does not run	Enablement, future timestamp, UTC Cron, valid target, logs
Wrong state after disconnect	Conversation selection, WebSocket proxy, background execution; in InProcess mode, running conversations show Interrupted after a Server restart and do not continue

Example: the page opens but the agent does not reply

Check whether Chat is waiting for approval or information, and respond if needed.
Send a plain text question through the same model connection. If it fails, check the API endpoint, model ID, and credentials.
If text works but a tool task fails, check tool bindings, directories, and host permissions.
In split deployments, a working management page with a failed chat connection suggests checking that /api/hubs/exec routes to Data Plane and supports WebSocket.
Find the specific error in Server logs at the recorded time. Repeat the same small task after the fix.

This sequence separates model, tool, and connection failures without changing several settings at once.