Troubleshooting: Proxy Not Starting

By default, the AgentSecrets proxy binds to localhost:8765. If another application is already using this port, the proxy will fail to start and throw an EADDRINUSE or bind: address already in use error.

Solution: Start the proxy on a different port using the --port flag:

agentsecrets proxy start --port 9000

Note: If you change the port, ensure your AI agents or tools are configured to route traffic to http://localhost:9000/proxy.

The local proxy daemon validates caller identity using a pre-shared session token stored in the OS Keychain (X-AS-Session-Token). If the token becomes desynchronized or rejected:

Solution: Rotate the local proxy session token:

agentsecrets proxy rotate-session

This generates a new cryptographically secure token, notifies the running daemon, and updates your secure OS Keychain without requiring a full account logout.

If your cloud authentication session is expired, re-authenticate your CLI session:

agentsecrets login

The proxy resolves credentials directly from your native OS Keychain via the keychain-auth security broker. On headless Linux servers or WSL environments, keychain access might require unlocking or configuring D-Bus/secret-service.

Solution: Check keychain and proxy status:

agentsecrets status
keychain-auth status --json

If the keychain is locked, follow your OS-specific instructions to unlock your login keyring or verify that keychain-auth is authorized:

sudo keychain-auth authorize $(which agentsecrets) AgentSecrets

If the proxy starts but immediately crashes, inspect the background audit logs for fatal errors:

agentsecrets proxy logs --last 10

Look for explicit error messages during the BOOT phase.

The proxy strictly binds to127.0.0.1 (localhost) for security. It will purposefully reject bindings to 0.0.0.0, as exposing the proxy to the local network is a severe security risk.