Instance administration

Enable AI coworkers and MCP

Configure the Docker installation, publish the right URLs and verify discovery before connecting a client.

Use the current installer and application images

Use the current Docker installer and API/Web images that include AI coworkers. This guide describes its public API port and configuration settings. The feature is off by default. Your Docker volumes retain application keys, OAuth credentials, records and attachments when containers are recreated.

Enable a local installation

Edit the generated .env in the installer directory. With the default ports, the Web app is at http://localhost:3000 and the MCP server is at http://localhost:8000/mcp. These localhost addresses are usable only from the installation machine. Desklog supplies the server and permissions, not an AI model.

DESKLOG_COWORKERS_ENABLED=true
DESKLOG_PUBLIC_API_URL=http://localhost:8000

Apply configuration normally

Run Compose again after editing .env. It recreates the affected containers, runs pending migrations and reuses persistent credentials. A plain container restart does not apply changed Compose environment values. If you were already signed in before enabling the feature, sign out and back in to obtain the coworker-management scope.

docker compose up -d

Give remote clients public HTTPS origins

For remote use, configure separate Web and API HTTPS hostnames. Origins must have no path or trailing slash. Keep the default loopback bindings when a reverse proxy runs on the same host. Changing the API origin also changes the MCP resource identity, so existing clients need reauthorization.

DESKLOG_WEB_URL=https://desklog.example.com
DESKLOG_PUBLIC_API_URL=https://api.example.com
DESKLOG_COWORKERS_ENABLED=true
# Replace with the actual immediate proxy IP or CIDR:
DESKLOG_TRUSTED_PROXIES=172.19.0.1

Configure the reverse proxy

Route the Web hostname to 127.0.0.1:3000 and the API hostname to 127.0.0.1:8000. Preserve Host and set X-Forwarded-Proto, X-Forwarded-Port and X-Forwarded-For correctly. Allow POST bodies for OAuth and MCP, and do not buffer streaming MCP responses. Serve a certificate trusted by the client. The public API origin must be reachable from that client, not just from Docker.

Trust only your immediate proxy

Set DESKLOG_TRUSTED_PROXIES to the proxy IP or CIDR actually seen by the API. For a host-based proxy on Linux, the Docker network gateway is a useful starting point; confirm it for your setup and recheck after network recreation. Leave the setting empty for direct localhost access. The API automatically trusts the hostname from its public origin; avoid wildcard host or proxy rules.

docker inspect "$(docker compose ps -q api)" \
  --format '{{range .NetworkSettings.Networks}}{{.Gateway}}{{end}}'

Keep internal and external addresses separate

DESKLOG_PUBLIC_API_URL controls the external API origin and derived /mcp resource. Web-to-API requests and the API’s token exchange continue to use http://api:8000 inside Docker. Do not replace these internal addresses with the host’s localhost URL. Change DESKLOG_API_PORT only when needed and update the public URL or proxy upstream to match.

Verify the advertised endpoints

The authorization-server response must advertise the public API issuer, registration and token endpoints, plus the Web authorization URL. Protected-resource discovery must report the exact /mcp URL. An unauthenticated MCP request should return 401 with resource-discovery information; a proxy 404 or an HTML page indicates routing is wrong.

curl -fsS https://api.example.com/.well-known/oauth-authorization-server
curl -fsS https://api.example.com/.well-known/oauth-protected-resource/mcp

Allow browser origins only when needed

Native or server-side clients normally send no Origin header. If your client does send one, list its exact origin in DESKLOG_MCP_ALLOWED_ORIGINS, separated by commas. Unlisted origins are rejected. This setting is an origin check, not a general CORS switch or a promise that every browser client supports this authentication flow.

Connect an identity and test a read

Follow Set up an AI coworker to create the identity, obtain Desk-owner approval and complete client consent. Run coworker_context, check the identity and Desk, then try a read-only task listing. Discovery alone does not verify a working OAuth connection.

Disable or revoke

Set DESKLOG_COWORKERS_ENABLED=false and run docker compose up -d to turn off coworker/MCP endpoints; MCP and coworker discovery/registration return 404. This does not erase data or revoke existing credentials. Revoke a connection, remove Desk access or disable the coworker when the access should stay removed after the feature is re-enabled.

Report a problem