Note:
Beta: The remote control feature is currently in the Beta stage, and its features and APIs may change in later versions. You are welcome to try it and provide 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, and the Web interface is only a remote window.
Overview
Remote Control starts a Gateway service locally and exposes a Web UI through Cloudflare Tunnel or the LAN, allowing you to connect to a running CodeBuddy Code session from any device.
With Remote Control, you can:
Use the Complete Local Environment Remotely: The file system, MCP servers, and tool configurations all remain available.
Interact with the Agent Through the Web UI: Send messages, view conversations, and monitor tool execution in the browser.
Connect from Multiple Devices: Scan a QR code with your phone to connect, with support for LAN and public network access.
Manage Sessions Through the Terminal: Work in the terminal and on the Web simultaneously, with conversations kept in sync.
Prerequisites
CodeBuddy Code is installed and you are logged in (run codebuddy and then use /login to log in).
If public network access is required, install cloudflared (optional). Starting Remote Control
Start the remote control service by using the /gateway command in a CodeBuddy Code session:
After a successful startup, the terminal displays the 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
After the Gateway starts, 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 directly access the Local address (such as http://10.x.x.x:8321).
Subcommands
|
/gateway
| Start Gateway (with Tunnel by default). |
/gateway status
| View current Gateway status. |
/gateway stop
| Stop Gateway. |
/gateway token
| Regenerate the authentication token. |
/gateway tunnel
| Start Gateway with Tunnel. |
Network Mode
Gateway supports two network modes to accommodate different usage scenarios:
Tunnel Mode (Default)
A temporary public domain name (*.trycloudflare.com) is automatically assigned through Cloudflare Quick Tunnel, and it can be accessed from the public network without any additional configuration.
Applicable scenarios:
Access remotely from an external network (such as a mobile network).
You do not want to configure port forwarding or a VPN.
You need to install cloudflared:
brew install cloudflared
curl -L https://pkg.cloudflare.com/cloudflared-stable-linux-amd64.deb -o cloudflared.deb
sudo dpkg -i cloudflared.deb
winget install Cloudflare.cloudflared
LAN Mode
If cloudflared is not installed or the Tunnel fails to start, Gateway automatically falls back to LAN mode. In this mode, only devices on the same network can access it.
Default listening port: 8321
Listening address: 127.0.0.1 by default (local machine only). You can listen on all network interfaces by using --host 0.0.0.0.
Security Mechanism
Authentication
When Gateway starts, it automatically generates a random password (token). Access to both the Web UI and API requires authentication. The following authentication methods are supported:
|
URL parameter | ?password=<token>, suitable for quickly sharing links.
|
Cookie | Automatically set after login, and no repeated authentication is required for subsequent access. |
Bearer Token | Authorization: Bearer <token>, suitable for API calls.
|
The password can be regenerated by running the /gateway token command. After regeneration, the previous password immediately becomes invalid.
Login Rate Limiting
To prevent brute-force attacks, the authentication middleware has a built-in login rate-limiting mechanism:
A maximum of 2 failed attempts are allowed per minute.
An additional 12 failed attempts are allowed per hour.
Login requests will be temporarily rejected after the limit is exceeded.
Permission
Tasks executed through 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 people.
CORS Policy
By default, Gateway allows cross-origin requests from the following origins:
Local loopback origins of the service's own listening port (localhost, 127.0.0.1, [::1] + the actual port)
The public IP address assigned by Tunnel
Additional origins configured through gateway.corsOrigins
Note:
localhost pages on other ports are no longer automatically allowed, to prevent pages on any local port from making cross-origin calls to process execution or file read/write interfaces. They must be explicitly declared in gateway.corsOrigins or CODEBUDDY_CODE_CORS_ORIGINS.
Three configuration modes are supported:
Exact match: https://example.com
Subdomain wildcard: https://*.example.com (matches all subdomains, including multi-level subdomains such as a.b.example.com)
Allow all: *
Web UI
The Web UI provides a complete interactive interface for CodeBuddy Code, including:
Conversation interface: Send messages, view Agent replies, and monitor tool calls.
Terminal panel: A built-in Web terminal that allows you to operate a remote terminal directly in the browser.
Instance management: View and manage multiple CodeBuddy Code instances.
Theme switching: Supports light and dark themes.
Multilingual: Supports switching between Chinese and English interfaces.
The Web UI communicates with the local Agent based on ACP (Agent Client Protocol), ensuring an experience completely consistent with terminal interaction.
Configuration
Settings Configuration
You can configure Gateway-related options in ~/.codebuddy/settings.json:
{
"gateway": {
"auth": "password",
"password": "your-custom-password",
"corsOrigins": ["https://your-domain.com", "https://*.example.com"],
"maxConnections": 5,
"tokenTtlMs": 86400000
}
}
|
auth
| Authentication mode, "password" or "none". Defaults to "password" when --serve is not explicitly configured. | "password"(--serve)
|
password
| Custom password. If left empty, a password is automatically generated on first startup. | Automatically generated |
corsOrigins
| List of additional allowed CORS origins. Supports exact origins, *.domain subdomain wildcards, and * to allow all. | []
|
maxConnections
| Maximum concurrent connections for ACP | 5
|
tokenTtlMs
| Validity period of ACP Session Token (in milliseconds) | 86400000 (24 hours)
|
Environment Variable
|
CODEBUDDY_CODE_CORS_ORIGINS
| Additional allowed CORS origins (comma-separated). Supports exact origins, *.domain subdomain wildcards, and * to allow all. For example, https://*.example.com,https://specific.com |
Managing Instances
When you run CodeBuddy Code in multiple project directories, each instance is automatically registered in the local instance registry (~/.codebuddy/instances.json). The instance management panel in the Web UI allows you to 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)
Gateway provides Webhook endpoints for integrating with enterprise communication platform bots:
{gateway-url}/gateway/webhook/:platform
Supported platform adapters:
|
WeCom | wecom
|
DingTalk | dingtalk
|
Feishu | feishu
|
General | generic
|
After configuring the Webhook callback URL of the enterprise bot to the endpoint above, you can send messages to CodeBuddy Code and receive replies through the enterprise communication platform.
Connection and Security
Gateway only starts an HTTP service locally and does not open inbound ports on your machine.
Public network access is achieved through outbound connections from Cloudflare Tunnel.
All Tunnel traffic is transmitted with Cloudflare's TLS encryption.
When Quick Tunnel is started with a fixed port, the Quick Tunnel domain remains unchanged across CLI restarts (see Keeping Tunnel Domains Stable).
Limit
One Gateway per session: Each CodeBuddy Code instance supports only one Gateway service at a time.
The terminal must remain running: Gateway runs as a local process. If you close the terminal or stop the CodeBuddy Code process, the remote connection is disconnected. Use /gateway to restart it.
Temporary nature of Quick Tunnel domains: A Quick Tunnel domain remains unchanged while the cloudflared process is alive. Starting with a fixed port allows the cloudflared process to be reused across CLI restarts (see Keeping Tunnel Domains Stable). If the cloudflared process exits (for example, due to a machine restart), the domain is reassigned. To permanently fix a domain, use a Named Tunnel (a Cloudflare account is required).
LAN mode limitation: When cloudflared is not installed, access is limited to devices on the same network.
Keeping Tunnel Domain Names Stable
By default, Quick Tunnel assigns a new random domain each time cloudflared starts. You can keep the domain unchanged across multiple CLI restarts by specifying a fixed port.
Using a Fixed Port
Start the CLI with a fixed port specified by the --port parameter:
In this way, the same port is used each time, and /gateway automatically reuses the previous cloudflared process and domain.
Note:
If --port is not specified, the system assigns a random port, and the port differs each time, making it impossible to match an existing cloudflared process.
Stopping a Tunnel
Running /gateway stop terminates the cloudflared process and clears its state. The next startup will assign a new domain.
If you only exit the CLI (Ctrl+C or /exit), the cloudflared process continues running and waits to be reused the next time the CLI starts.
References
Settings: Configure Gateway-related options. Hooks: Custom commands to run before and after tool execution.