Troubleshooting

Common issues and how to fix them

Agent Connection Issues

Agent won't start

  • • Check Node.js version: Run node --version. Must be 18+.
  • • Verify token format: Token should start with cf_ followed by 32 hex characters.
  • • Run with debug: cloudforge-agent --token YOUR_TOKEN --debug

Agent connects but shows "offline"

  • • Token mismatch: Ensure you're using the correct token for this server.
  • • Regenerate token: Go to server settings and regenerate the token.
  • • Check agent logs: Look for authentication errors in the debug output.

Connection drops frequently

  • • Network stability: Check your server's internet connection.
  • • Firewall: Ensure outbound connections to cloud-forge.me:443 are allowed.
  • • Run as service: Use systemd/launchd for automatic reconnection.

Terminal Issues

Terminal shows "Waiting for Agent"

  • • Agent not running: Start the agent on your server.
  • • Check server status: Go to My Servers and verify status is "Online".

Terminal is slow or laggy

  • • Network latency: Ping cloud-forge.me to check latency.
  • • Browser performance: Try a different browser or close other tabs.
  • • Server location: Use a server closer to your location.

Special keys not working (Ctrl+C, Tab, etc.)

  • • Browser shortcuts: Some browsers capture Ctrl+W, Ctrl+T, etc. Use the browser's focus mode if available.
  • • Mobile devices: Use the on-screen keyboard buttons for special keys.

Terminal display is garbled

  • • Reset terminal: Run reset or clear.
  • • TERM variable: Ensure TERM=xterm-256color is set.
  • • Resize: Resize your browser window to trigger a terminal resize.

AI Coding Tool Issues

Claude Code /login fails

  • • No browser: Copy the auth URL and open it on your local machine, then paste the code back.
  • • Alternative: Copy ~/.config/claude-code/auth.json from a local machine.

API key not working

  • • Check export: Run echo $ANTHROPIC_API_KEY (or relevant var) to verify it's set.
  • • New shell: If you added to .bashrc, run source ~/.bashrc.
  • • API limits: Check if you've hit rate limits on your API provider.

Rate limits / quota exceeded

  • • Wait: Rate limits typically reset within minutes to hours.
  • • Upgrade: Consider a higher tier subscription for more usage.
  • • Use /compact: In Claude Code, use /compact to reduce context and save tokens.

Account Issues

Can't add more servers

  • • Plan limit: Free plan = 1 server, Starter = 3, Pro = unlimited.
  • • Upgrade: Upgrade your plan for more servers.

Lost my agent token

  • • Regenerate: Go to server settings and click "Regenerate Token".
  • • Update agent: After regenerating, update the token on your server.

Still stuck?

If you can't find a solution here, please:

Contact Support
AI Tools Setup