OrcaCD Documentation

Agent stays Offline after connecting

Symptoms: The Agent is running but shows as Offline in the Hub UI.

Checks:

Verify HUB_URL in the Agent's .env is correct and reachable from the Agent's host.
Confirm the AUTH_TOKEN matches the token generated for that Agent in the Hub UI.
Check Agent logs: docker compose logs agent and look for connection errors.
If the Hub is behind a reverse proxy, make sure WebSocket upgrades are forwarded correctly. See the Reverse Proxy guide.

Checks:

Confirm the Hub container is running: docker compose ps
Check Hub logs: docker compose logs hub
Verify your reverse proxy is forwarding to the correct port (default: 8080).
If you set TRUSTED_PROXIES, confirm the proxy's IP is included. An incorrect value can cause the Hub to reject requests.

Symptoms: An application stays in the syncing state indefinitely.

Checks:

Verify the Agent is online.
Check Agent logs for errors during the Docker Compose up/pull step.
Ensure the Agent has access to the Docker socket (/var/run/docker.sock).
If the Compose file references private images, confirm the Agent host has credentials to pull them (e.g., docker login was run on that host).

Symptoms: Sync status shows failed with an authentication error.

Checks:

Confirm the auth token is still valid and has not expired or been revoked.
For token auth, verify the token has read_repository (GitLab) or Contents: read (GitHub) permissions.
Use the Test Connection button in the repository settings to check credentials without triggering a full sync.

Symptoms: Pushes to the repository do not trigger a sync.

Checks:

Confirm the webhook URL and secret in your Git provider match what OrcaCD shows in the repository settings.
Check that the Hub is publicly reachable on the configured APP_URL.
Review the webhook delivery logs in your Git provider (GitHub: Settings → Webhooks → Recent Deliveries) to see if the request reached the Hub.
Verify the webhook is configured to send push events.

If you locked yourself out by disabling local authentication, see Account Recovery.

If your issue is not listed here, please report it in GitHub Issues.