Common Issues

Can't connect to the server

Symptoms: Connection times out or fails immediately.

Fixes:

• Verify both devices are on the same WiFi (for local mode).
• Check that the Mac app / server is actually running.
• Confirm the IP address and port are correct. Run ipconfig getifaddr en0 on your Mac.
• If macOS Firewall is enabled, allow incoming connections for the app.
• Disable VPN on both devices if it routes traffic differently.
• Corporate/hotel WiFi may isolate devices. Try a home network or phone hotspot.

Can't type dots in the IP address

Symptom: Some locales (German, French) show a comma , instead of . on the numeric keyboard.

Fix: Switch to the standard alphabet keyboard to type dots, or paste the IP address from Notes.

Connected but terminal is blank

Symptom: Green connection indicator, but the terminal view shows nothing.

Fixes:

1. Open the session selector and re-select your session.
2. If no sessions appear, create a new one.
3. If a session exists but has no output, tap Start to launch Claude Code.

Tapping Start seems to do nothing

Symptom: You tap Start but nothing changes.

This is expected if Claude Code is already running. The app has duplicate-start protection. Check the status indicator -- if it shows Running (green), Claude Code is already active. Just start sending prompts.

Notifications not arriving

Symptom: Claude Code finishes tasks but no push notification appears.

Fixes:

• Check iOS Settings > Tactic Remote > Notifications -- must be enabled.
• Make sure the server and app are on the latest version.
• Notifications require Claude Code hook events. These are sent automatically but rely on the WebSocket connection being reachable.

Connection drops when app is backgrounded

Symptom: Coming back to the app after a while shows a disconnected state.

This is normal iOS behavior. iOS suspends background network connections to save battery. The app automatically reconnects when you return.

For long tasks, rely on push notifications rather than keeping the app open.

Server IP keeps changing

Symptom: Your Mac gets a different IP each time, breaking the saved connection.

Fixes:

• Assign a static IP to your Mac in System Settings > Network.
• Use Bonjour auto-discovery instead of a manual IP.
• Use a Cloudflare Tunnel for a stable URL.

Claude Code says "API key not set"

This is a Claude Code error, not a Tactic Remote error. Claude Code needs an Anthropic API key to function.

Set it in your terminal:

export ANTHROPIC_API_KEY="your-anthropic-api-key"

Or run claude config to set it permanently.

Note: This is separate from the Tactic Remote server API key. The Anthropic key is for the Claude AI service. The server API key is for authenticating the iPhone-to-Mac connection.

Need more help?

Visit the Support page or open an issue on GitHub with:

• App version
• Connection mode (Local or Cloudflare Tunnel)
• What you tried and what happened