Remote Control ​

Beta: The Remote Control feature is currently in Beta. Functionality and interfaces may change in future versions. We welcome you to try it out and share feedback.

With Remote Control, you can remotely access a locally running CodeBuddy Code session from your phone, tablet, or any browser. The session always runs on your local machine — the Web UI is simply a remote window.

Overview ​

Remote Control starts a Gateway service locally and exposes a Web UI through a Cloudflare Tunnel or your local network, allowing you to connect to a running CodeBuddy Code session from any device.

With Remote Control, you can:

  • Use your full local environment remotely: File system, MCP servers, and tool configurations all remain available
  • Interact with the Agent via Web UI: Send messages, view conversations, and monitor tool execution in a browser
  • Connect from multiple devices: Scan a QR code on your phone to connect, with both LAN and public network access supported
  • Manage sessions from the terminal: Work simultaneously in the terminal and the Web UI, with conversations kept in sync

Prerequisites ​

  • CodeBuddy Code installed and logged in (run codebuddy and use /login to log in)
  • For public network access, install cloudflared (optional)

Starting Remote Control ​

Use the /gateway command in a CodeBuddy Code session to start the Remote Control service:

/gateway

On successful startup, the terminal displays connection information:

Gateway started

  ├─ Status   connected
  ├─ Mode     tunnel
  ├─ Local    http://127.0.0.1:8321
  ├─ Tunnel   https://xxx-xxx-xxx.trycloudflare.com
  ├─ Web UI   https://xxx-xxx-xxx.trycloudflare.com/?password=<token>
  └─ Webhook  https://xxx-xxx-xxx.trycloudflare.com/gateway/webhook/:platform

  Scan to open Web UI:

  [QR Code]

Connection Methods ​

Once the Gateway is started, you can connect from other devices in the following ways:

  • Scan the QR code: Scan the QR code displayed in the terminal with your phone to open the Web UI directly
  • Copy the Web UI link: Open the URL with the authentication token in any browser
  • LAN access: Devices on the same network can access the Local address directly (e.g., http://10.x.x.x:8321)

Subcommands ​

CommandDescription
/gatewayStart the Gateway (with Tunnel by default)
/gateway statusView the current Gateway status
/gateway stopStop the Gateway
/gateway tokenRegenerate the authentication token
/gateway tunnelStart the Gateway with Tunnel

Network Modes ​

The Gateway supports two network modes for different use cases:

Tunnel Mode (Default) ​

Automatically assigns a temporary public domain (*.trycloudflare.com) through Cloudflare Quick Tunnel, allowing public network access without any additional configuration.

Use cases:

  • Remote access from external networks (e.g., mobile data)
  • No need to configure port forwarding or VPN

Requires cloudflared to be installed:

bash
# macOS
brew install cloudflared

# Debian/Ubuntu
curl -L https://pkg.cloudflare.com/cloudflared-stable-linux-amd64.deb -o cloudflared.deb
sudo dpkg -i cloudflared.deb

# Windows
winget install Cloudflare.cloudflared

LAN Mode ​

When cloudflared is not installed or the Tunnel fails to start, the Gateway automatically falls back to LAN mode. In this mode, only devices on the same network can access the service.

  • Default listening port: 8321
  • Listening address: 0.0.0.0 (all network interfaces)

Security ​

Authentication ​

The Gateway automatically generates a random password (token) on startup. Authentication is required to access both the Web UI and the API. The following authentication methods are supported:

MethodDescription
URL parameter?password=<token>, convenient for quickly sharing links
CookieAutomatically set after login; subsequent access requires no re-authentication
Bearer TokenAuthorization: Bearer <token>, suitable for API calls

The password can be regenerated using the /gateway token command. Once regenerated, the previous password is immediately invalidated.

Login Rate Limiting ​

To prevent brute-force attacks, the authentication middleware includes built-in login rate limiting:

  • A maximum of 2 failed attempts per minute
  • An additional 12 failed attempts allowed per hour
  • Login requests are temporarily rejected once the limit is exceeded

Permissions ​

Tasks executed via Remote Control automatically run in bypassPermissions mode, meaning tool execution does not require individual approval. This is because interactive approval is not possible in remote scenarios. Make sure to share the access link only with trusted individuals.

CORS Policy ​

The Gateway allows cross-origin requests from the following origins by default:

  • Loopback addresses (localhost, 127.0.0.1, [::1])
  • The public address assigned by the Tunnel
  • Additional origins configured via gateway.corsOrigins

Web UI ​

The Web UI provides a complete CodeBuddy Code interaction interface, including:

  • Chat interface: Send messages, view Agent responses, and monitor tool calls
  • Terminal panel: Built-in web terminal for operating the remote terminal directly in the browser
  • Instance management: View and manage multiple CodeBuddy Code instances
  • Theme switching: Support for light/dark themes
  • Multi-language: Support for Chinese/English interface switching

The Web UI communicates with the local Agent via ACP (Agent Client Protocol), ensuring an experience fully consistent with terminal interaction.

Configuration ​

Settings Configuration ​

Gateway options can be configured in ~/.codebuddy/settings.json:

json
{
  "gateway": {
    "auth": "password",
    "password": "your-custom-password",
    "corsOrigins": ["https://your-domain.com"],
    "maxConnections": 5,
    "tokenTtlMs": 86400000
  }
}
KeyDescriptionDefault
authAuthentication mode, "password" or "none""none"
passwordCustom password. Auto-generated on first startup if emptyAuto-generated
corsOriginsList of additional allowed CORS origins[]
maxConnectionsMaximum number of concurrent ACP connections5
tokenTtlMsACP Session Token TTL in milliseconds86400000 (24 hours)

Environment Variables ​

Environment VariableDescription
CODEBUDDY_CORS_ORIGINSAdditional allowed CORS origins (comma-separated)

Instance Management ​

When you run CodeBuddy Code in multiple project directories, each instance automatically registers with the local instance registry (~/.codebuddy/instances.json). The Web UI's instance management panel lets you view all active instances and switch between them.

Instance information includes:

  • Working directory
  • Local/Tunnel address
  • Operating system and architecture
  • Start time and running status

Third-Party Platform Integration (Webhook) ​

The Gateway provides a Webhook endpoint for integrating with enterprise messaging platform bots:

{gateway-url}/gateway/webhook/:platform

Supported platform adapters:

PlatformIdentifier
WeComwecom
DingTalkdingtalk
Feishu (Lark)feishu
Genericgeneric

After configuring your enterprise bot's Webhook callback URL to the above endpoint, you can send messages to CodeBuddy Code through the enterprise messaging platform and receive replies.

Connection and Security ​

  • The Gateway only starts an HTTP service locally and does not open inbound ports on your machine
  • Public access is achieved through Cloudflare Tunnel's outbound connections
  • All Tunnel traffic is encrypted via Cloudflare's TLS
  • Each Quick Tunnel startup assigns a new random domain name

Limitations ​

  • One Gateway per session: Each CodeBuddy Code instance supports only one Gateway service at a time
  • Terminal must remain running: The Gateway runs as a local process. The remote connection is lost when the terminal is closed or the CodeBuddy Code process is stopped. Use /gateway to restart
  • Quick Tunnel domain is temporary: Each Quick Tunnel startup assigns a different domain. For a fixed domain, use a Named Tunnel (requires a Cloudflare account)
  • LAN mode limitation: Without cloudflared installed, access is limited to devices on the same network