Troubleshooting

Common issues and how to fix them.

Terminal Issues

Terminal shows blank screen

Cause: node-pty binary incompatibility

Fix: Rebuild node-pty for your Node version:

npm rebuild node-pty --build-from-source

Terminal colors not working

Cause: TERM variable not set correctly

Fix: The terminal automatically sets TERM=xterm-256color. If issues persist, check your shell configuration.

”posix_spawnp failed” error

Cause: node-pty compiled for different Node version

Fix:

rm -rf node_modules/node-pty
npm install node-pty
npm rebuild node-pty --build-from-source

Tailscale Issues

”Serve is not enabled”

Cause: Tailscale Serve not enabled for your tailnet

Fix: Visit the URL shown in the error message to enable it.

”Not connected” error

Cause: Tailscale not running or not authenticated

Fix:

tailscale status  # Check status
tailscale up      # Connect

Can’t access from other devices

Cause: Devices not on the same tailnet

Fix: Make sure Tailscale is installed and connected on all devices.

Telegram Issues

Bot not responding

Possible causes:

  1. Invalid bot token
  2. User ID not in allowed list
  3. Server not running

Fix:

  1. Verify token from @BotFather
  2. Check your user ID with @userinfobot
  3. Restart the server

”Unauthorized” message

Cause: Your user ID is not in TELEGRAM_ALLOWED_USERS

Fix: Add the displayed user ID to your .env file.

Commands timeout

Cause: Command takes longer than 60 seconds

Fix: Use raw commands for long operations, or check if the command is stuck.

LLM Issues

”OPENAI_API_KEY not set”

Cause: API key not configured

Fix: Add your OpenAI API key to .env:

OPENAI_API_KEY=sk-your-key-here

“Invalid API key”

Cause: API key is incorrect or expired

Fix: Generate a new key at platform.openai.com

LLM responses are slow

Cause: API latency or model choice

Fix: Use a faster model:

OPENAI_MODEL=gpt-4.1-nano

“Rate limit exceeded”

Cause: Too many API requests

Fix: Wait a few minutes, or upgrade your OpenAI plan.

General Issues

Server won’t start

Check:

  1. Port 7860 is available: lsof -i :7860
  2. Node.js version is 18+: node -v
  3. Dependencies installed: npm install

High memory usage

Cause: Many terminal sessions open

Fix: Close unused browser tabs. Each tab creates a new session.

Getting Help

If your issue isn’t listed here:

  1. Check the GitHub Issues
  2. Open a new issue with:
    • Your OS and Node.js version
    • Error messages
    • Steps to reproduce