Troubleshooting

Common errors and how to fix them.

CLI

binboi: command not found

Cause: The CLI binary is not on your PATH.

Fix:

export PATH="/usr/local/bin:$PATH"

Add the line to ~/.zshrc or ~/.bashrc to make it persistent.

Login fails with connection refused to 127.0.0.1:8080

Cause: BINBOI_API_URL is pointing at localhost instead of the production API.

Fix:

unset BINBOI_API_URL
# or, to set it explicitly:
export BINBOI_API_URL=https://api.binboi.com

Tunnel fails with dial tcp to 127.0.0.1:8081

Cause: BINBOI_SERVER_ADDR is misconfigured. The default relay is api.binboi.com:8081.

Fix:

unset BINBOI_SERVER_ADDR
# or, to set it explicitly:
export BINBOI_SERVER_ADDR=api.binboi.com:8081

Note: binboi.com:8081 resolves to the Vercel-hosted frontend, not the relay. Always use api.binboi.com:8081.

binboi login succeeds but binboi whoami immediately fails

Cause: A stale BINBOI_AUTH_TOKEN (or BINBOI_SERVER_ADDR) is exported in your shell — env vars override ~/.binboi/config.json. Common symptoms:

• binboi login saves a fresh token, prints "Logged in as …".
• binboi whoami returns invalid or expired token.
• binboi http connects to the wrong relay or fails the handshake.

Fix:

# Clear the current shell.
unset BINBOI_AUTH_TOKEN BINBOI_TOKEN BINBOI_SERVER_ADDR BINBOI_API_URL
 
# Find and remove stale exports from shell startup files.
grep "BINBOI_" ~/.zshrc ~/.zshenv ~/.zprofile ~/.bashrc ~/.bash_profile 2>/dev/null

Restart the shell after editing dotfiles so the unset takes effect everywhere.

Auth

401 Unauthorized

Cause: Token revoked, malformed, or never created.

Fix: Generate a new token and log in again.

# Get a new token at https://binboi.com/dashboard/access-tokens
binboi login --token binboi_pat_<new>

403 TOKEN_LIMIT_REACHED

Cause: Your account is at its active token cap (2 on Free, 25 on Pro, 100 on Max).

Fix: Revoke an unused token from the dashboard, or upgrade your plan.

curl -X DELETE https://api.binboi.com/api/v1/tokens/<token_id> \
  -H "Authorization: Bearer binboi_pat_..."

Tunnels

403 TUNNEL_LIMIT_REACHED

Cause: Too many active tunnels (1 on Free, 10 on Pro, 50 on Max).

Fix: Close an existing tunnel or upgrade your plan.

binboi tunnels
# pick one and close it
curl -X DELETE https://api.binboi.com/api/v1/tunnels/<subdomain> \
  -H "Authorization: Bearer binboi_pat_..."

409 SUBDOMAIN_TAKEN

Cause: Someone else has already reserved that subdomain. Reserved subdomains are Pro/Max only and are first-come-first-served.

Fix: Pick a different subdomain.

binboi http 3000 my-app-2

Tunnel disconnects after a few seconds

Cause: Network instability or NAT timeout between your machine and the Frankfurt relay.

Fix: Restart the tunnel. If it keeps happening, contact support.

binboi http 3000

Account

Tunnel handshake fails with "access token has been revoked" — but the token is fresh

Cause: The tunnel reject path returns a generic "revoked" error regardless of the actual reason. The most common non-obvious cause is an account flipped to is_active = false (typically by the Polar cancellation webhook), not a real token revocation.

Fix (hosted): Email contact@miransas.com with your account email. Support can reactivate the account.

Fix (self-hosted): Set the user back to active in the database:

UPDATE "user" SET is_active = true WHERE email = '<your-email>';

A backend fix to distinguish revoked-token, revoked-account, and unknown-user errors is planned.

Email verification not arriving

Cause: Mail filters or a typo at signup.

Fix:

1. Check your spam folder.
2. Request a new verification email from the login page.
3. If still missing, email contact@miransas.com.

Still stuck? Email contact@miransas.com with your token prefix (first 12 chars only, not the full token) and a description of what you've tried.

Next

• CLI reference — all commands, flags, and env vars.
• API reference — full list of error codes.
• HTTP tunnels — how routing and quotas work.