Remote access: control CodexUse over Tailscale
CodexUse 2.5 ships a built-in TCP daemon that exposes your workspace over the network. If you run Tailscale, the app auto-detects your hostname and suggests a connection string. Sit on your couch with a phone and steer your running Codex session from there.
How it works
The TCP daemon is a JSON-RPC 2.0 server that runs inside the CodexUse Electron process. When started, it listens on a configurable port (default: 4732) and accepts authenticated connections.
- Authentication: Each connection must present a token within 30 seconds. The token is compared using timing-safe equality to prevent timing attacks.
- Full API surface: The daemon exposes the same operations you use in the GUI: start threads, resume conversations, send messages, respond to approvals, list workspaces, and more.
- Real-time events: All Codex events (tool calls, approvals, notifications) are broadcast to connected clients as JSON-RPC notifications.
- Connection limits: Max 10 concurrent connections, 2 MB max message size.
Tailscale auto-detection
If Tailscale is installed and running, CodexUse automatically detects:
- Your Tailscale DNS name (e.g.
macbook.your-tailnet.ts.net) - Your tailnet name, hostname, and IP addresses
- Whether Tailscale is currently connected
It then generates a suggested connection string like macbook.your-tailnet.ts.net:4732 that you can hand to the remote client.
Setting it up
- Open Settings → Remote (under the CodexUse group).
- The daemon status and Tailscale detection appear automatically.
- Copy the connection string and token.
- On the remote device, enter the host and token in the connection setup.
- Hit Test connection to verify.
What you can do remotely
- Start new conversations and resume existing ones
- Send messages and steer running turns
- Respond to exec and apply-patch approval requests
- List workspaces and threads
- Subscribe to live thread events
- Read account info and rate limits
Security model
- Token-based auth with
crypto.timingSafeEqualto prevent timing attacks - 30-second auth timeout per connection — unauthenticated connections are dropped
- Max 10 concurrent connections
- 2 MB max message size
- Over Tailscale, all traffic is encrypted by WireGuard at the network layer
- Without Tailscale, the TCP connection is unencrypted — only use on trusted networks
Troubleshooting
| Symptom | Likely cause | Action |
|---|---|---|
| Cannot connect from remote device | Tailscale not running or firewall blocking the port | Check tailscale status on both devices. Make sure both are on the same tailnet. |
| Connection drops after 30 seconds | Token not sent in time | The daemon requires authentication within 30 seconds of connecting. Check the client is sending the token immediately. |
| Tailscale not detected | Tailscale binary not in expected path | CodexUse checks /usr/local/bin/tailscale, /Applications/Tailscale.app/Contents/MacOS/Tailscale, and /opt/homebrew/bin/tailscale. Make sure Tailscale is installed and accessible. |
| Events not arriving on remote client | Client not subscribed to the thread | Use the thread/live/subscribe RPC method to start receiving events for a specific thread. |
Related
Do I need Tailscale for remote access?
Tailscale is not strictly required, but it is the recommended and auto-detected path. The TCP daemon listens on a port, so any network route to your machine works. Tailscale just makes it easy and secure with automatic DNS names and encrypted connections.
Is the remote connection encrypted?
The TCP daemon uses token-based authentication with timing-safe comparison. Over Tailscale, all traffic is encrypted by WireGuard. Without Tailscale, the connection is unencrypted at the application layer, so use it on trusted networks only.
How many remote connections can I have?
Up to 10 concurrent connections. Each must authenticate within 30 seconds. Messages are capped at 2 MB.