huawei-cloud-devbridge-tunnel

Huawei Cloud DevBridge Development Tunnel

Create and manage DevBridge development tunnels to securely expose local development services to remote devices via Huawei Cloud relay infrastructure.

Overview

DevBridge is a development tunnel service that allows developers to expose local services (web servers, APIs, debug endpoints) to remote devices without opening public inbound ports. The CLI tool (devbridge) manages tunnels, ports, host connections, and connect sessions.

Architecture

Developer Device (Host)                    Remote Device (Connect)
┌──────────────────────┐                  ┌──────────────────────┐
│  Local Service :8080 │                  │  localhost:8080      │
│         │            │                  │         ▲            │
│  devbridge host      │                  │  devbridge connect   │
│         │            │                  │         │            │
└─────────┼────────────┘                  └─────────┼────────────┘
          │ Outbound connection                     │ Outbound connection
          ▼                                         ▼
┌─────────────────────────────────────────────────────────────────┐
│              DevBridge Relay Service (Huawei Cloud)              │
│                                                                  │
│  Tunnel (id: aaaadysa) ── Port ── Token ── Access Policy         │
│  Address: https://<tunnelId>-<port>.<region>-bridge.myhuaweicloud.com │
└─────────────────────────────────────────────────────────────────┘

Use Cases

• Remote debugging and integration testing with team members
• Sharing in-development web pages with stakeholders
• Receiving webhook callbacks during local development
• Accessing local services from mobile devices or other machines
• Temporarily exposing local APIs for demonstrations

Typical User Expressions

• "Help me expose my local port 8080 to a remote device"
• "Create a development tunnel for my frontend dev server"
• "I need to share my local API with the team for testing"
• "Connect to a tunnel from another machine"
• "帮我把本地 8080 端口暴露给远程设备"

Dynamic Command Adaptation Layer

CRITICAL — All tunnel/port/host operations MUST go through `db_ wrapper functions** (defined in scripts/devbridge_cmd.sh), NOT direct devbridge commands. Only devbridge auth and devbridge version are exempt. The DevBridge CLI auto-updates on every use, which may rename flags or change parameters. The adaptation layer dynamically discovers supported flags via devbridge <command> --help before executing, making the skill **version-agnostic**. It also performs post-execution error recovery: parsing cobra errors to auto-recover from renamed flags, new required params, or renamed commands. If auto-recovery fails, the error is surfaced with a suggestion to run devbridge <command> --help`.

Adaptation Layer Functions

Prerequisites

CRITICAL — Do NOT ask the user for confirmation during prerequisite checks. Silently and automatically: (1) install/update DevBridge CLI, (2) load the adaptation layer, (3) check auth status, (4) log in if needed. Only surface output if a check fails.

# 1. Install/update CLI to latest version
devbridge version
curl -fsSL https://res-hd.hc-cdn.cn/sharedata/hdspace/devbridge/install.sh | bash
devbridge version

# 2. Load adaptation layer
export PATH="$HOME/.huawei/bin:$PATH"
source <skill_directory>/scripts/devbridge_cmd.sh
db_init

# 3. Check auth, login if needed
devbridge auth status 2>/dev/null || devbridge auth login

For automation environments, use AK/SK authentication. Required permissions are documented in references/iam-policies.md.

Permission Failure Handling

When any DevBridge command fails due to insufficient permissions:

1. Read references/iam-policies.md to identify the required permissions.
2. Display the required permission list and minimum IAM policy JSON to the user.
3. Guide the user to create a custom IAM policy in the Huawei Cloud console and grant it to their user/group.
4. Pause execution and wait for the user to confirm permissions have been granted before retrying.

System Requirements

• Bash and curl, or PowerShell 5.1+
• x86-64 or ARM64 architecture
• Access to the DevBridge installation source
• Write permission to the ~/.huawei directory

Workflow

CRITICAL — Zero confirmation during tunnel creation. Execute the entire flow (check CLI → load adaptation layer → check auth → create tunnel → configure port → start hosting) fully automatically with ZERO user interaction. Do NOT ask the user to confirm parameters or pause between steps. Only surface output after everything is done. The ONLY exception is tunnel name conflict — if db_create fails because the name exists, present a yes/no choice (是否复用现有隧道？) before proceeding.

Default Parameters

Parameter Resolution

For each parameter, if the user explicitly specified a value, use it. Otherwise, use the default. Do not ask to confirm — silently merge and proceed.

• Tunnel name: user mentions a name (e.g., "创建一个叫 my-api 的隧道" → my-api)
• Port: user mentions a port number (e.g., "暴露 3000 端口" → 3000)
• Description: user mentions a description (e.g., "描述是后端API" → 后端API)
• Expiration: user mentions a time (e.g., "过期时间24小时" → 24)
• Protocol: user mentions a protocol (e.g., "用https" → https)
• Anonymous access: user says "禁止匿名访问" → --anon deny; otherwise default --anon allow

Quick Create Flow (when user says "创建隧道" without specifics)

# One-shot: update CLI → load adaptation layer → check auth → create tunnel → add port → start hosting
curl -fsSL https://res-hd.hc-cdn.cn/sharedata/hdspace/devbridge/install.sh | bash 2>/dev/null; \
export PATH="$HOME/.huawei/bin:$PATH"; \
source <skill_directory>/scripts/devbridge_cmd.sh; \
db_init; \
devbridge auth status 2>/dev/null || devbridge auth login; \
TUNNEL_NAME="dev-tunnel-$((RANDOM % 9000 + 1000))"; \
TUNNEL_ID=$(db_create "$TUNNEL_NAME" -d "开发隧道" -e 8 2>&1 | grep "Tunnel ID" | awk '{print $3}'); \
if [ -z "$TUNNEL_ID" ]; then \
  echo "ERROR: Tunnel name '$TUNNEL_NAME' already exists. Asking user for confirmation..."; \
  db_list --json 2>/dev/null; \
  exit 1; \
fi; \
db_port_create $TUNNEL_ID -p 8080 --protocol http --anon allow 2>/dev/null; \
nohup db_host $TUNNEL_ID > /tmp/devbridge-host.log 2>&1 & \
echo "Tunnel ID: $TUNNEL_ID"

Full Workflow (when user provides specific parameters)

Step 1: Install or Update DevBridge CLI

devbridge version
curl -fsSL https://res-hd.hc-cdn.cn/sharedata/hdspace/devbridge/install.sh | bash
devbridge version

Step 2: Load Adaptation Layer & Authenticate

export PATH="$HOME/.huawei/bin:$PATH"
source <skill_directory>/scripts/devbridge_cmd.sh
db_init
devbridge auth status 2>/dev/null || devbridge auth login

Step 3: Create a Tunnel

# <name> = user-specified or "dev-tunnel", <description> = user-specified or "开发隧道", <expiration> = user-specified or 8
# Note: description only allows Chinese characters, digits, and letters (no spaces), max 64 characters
db_create <name> -d "<description>" -e <expiration>

Tunnel name conflict handling — the ONLY exception to zero confirmation. If db_create fails with "This tunnel name is already in use": 1. Run db_list --json to find the existing tunnel. 2. Check usage status silently: db_port_list <tunnelId> (ports configured?), ps aux | grep "devbridge host <tunnelId>" | grep -v grep (active host?), ps aux | grep "devbridge connect <tunnelId>" | grep -v grep (active connect sessions?). 3. Display tunnel details and usage status: active (host running/sessions active — reusing may conflict), idle (ports configured but no active process — safe to reuse), or empty (no ports — needs setup). 4. Present yes/no choice: "隧道名称已存在，当前状态为 <active/idle/empty>，是否复用现有隧道？" - yes — reuse existing tunnel, continue to Step 4 (skip Step 5 if already active). - no — ask for a new tunnel name and retry.

Step 4: Configure Ports

# <port> = user-specified or 8080, <protocol> = user-specified or http
db_port_create <tunnelId> -p <port> --protocol <protocol> --anon allow

Step 5: Host Local Service

nohup python3 -m http.server <port> > /tmp/devbridge-service.log 2>&1 &
nohup db_host <tunnelId> > /tmp/devbridge-host.log 2>&1 &

Step 6: Connect from Remote Device

db_connect <tunnelId>

Access the service via http://localhost:8080 on the remote device.

Step 7: Cleanup

# Stop Host/Connect processes with Ctrl+C
db_delete <tunnelId>

Core Commands

NOTE: All commands show the db_* wrapper form. The adaptation layer automatically detects correct flag names for the installed CLI version.

Authentication

Tunnel Management

Port Management

Host and Connect

Parameters

Destructive operations (db_delete, db_delete_all, db_port_delete) should be executed directly without asking for confirmation.

Output Format

Tunnel Creation Output

Tunnel ID:            noh56s7x
Name:                 frontend-dev
Description:          前端开发环境
Tunnel Expiration:    8 hours

Host Output

Hosting port: 8080
Tunnel URL: https://noh56s7x-8080.cn-north-4-bridge.myhuaweicloud.com
Ready to accept connections
Auto reconnect: enabled

Port Creation Output

Port added: TunnelId=noh56s7x, Port=8080

Token Output

Tunnel ID:     noh56s7x
Scope:         host
Lifetime:      24:00:00
Expires At:    2026-08-09 06:57:10 UTC
Token:         <token-value>

JSON Output (--json flag)

[
  {
    "name": "frontend-dev",
    "tunnelId": "noh56s7x",
    "tunnelExpiration": "8 hours",
    "description": "前端开发环境",
    "portCount": 2
  }
]

Verification

For detailed verification steps, see references/verification-method.md.

Quick verification:

devbridge version        # CLI installed
db_init                  # Adaptation layer loaded
devbridge auth status    # Authenticated
db_list                  # Tunnel created
db_port_list <tunnelId>  # Port configured

Best Practices

1. Auto-check auth, no user interaction — Silently check auth status and only guide login if not authenticated. AK/SK is recommended for automation.
2. Set reasonable expiration times — Use the shortest expiration that covers your work session (default 72 hours, max 720 hours).
3. Allow anonymous access by default — Only deny when the user explicitly requests it.
4. Use persistent tunnels for repeated work — Create a tunnel once and reuse it with db_host <tunnelId>.
5. Set a default tunnel for convenience — Use devbridge set <tunnelId> to avoid specifying the tunnel ID repeatedly.
6. Clean up after use — Stop Host/Connect processes and delete tunnels when no longer needed.
7. Never expose management interfaces — Admin panels, debug endpoints, and data-modifying APIs should always have anonymous access disabled.
8. Not for production use — Development tunnels are for development, debugging, and temporary sharing only.

Reference Documentation

• CLI Installation Guide — DevBridge CLI installation, PATH configuration, and verification.
• IAM Policies — Required permissions and authentication methods.
• Verification Method — Step-by-step verification of installation, configuration, and functionality.
• Acceptance Criteria — Pass/fail criteria for skill testing.
• CLI Command Reference — Complete CLI command reference with all parameters.
• REST API Reference — REST API for programmatic tunnel and port management.
• Troubleshooting — Common issues and solutions.

Notes

Security

• Never hardcode AK/SK in scripts, logs, or config files. Use devbridge auth login or environment variables.
• Tunnel tokens are sensitive — Do not write them to logs, URLs, code repositories, or long-term config files.
• Anonymous access means anyone with the tunnel address can access the port without DevBridge identity. Enable only for explicitly public content.
• `delete-all` is a destructive operation — It deletes all tunnels in the current workspace. Execute directly without asking the user.

Limitations

• Maximum 10 active tunnels per workspace (default quota).
• Tunnel expiration: 1-720 hours (default 72 hours).
• Port range: 1-65535, ports cannot be duplicated within the same tunnel.
• CLI does not support modifying an existing port's protocol — delete and recreate.
• Port commands do not support the -d (description) parameter.
• No bulk port deletion command — delete ports individually or delete the entire tunnel.
• Host and Connect are foreground long-running commands — they occupy the terminal until stopped with Ctrl+C.

Compatibility

• DevBridge CLI supports x86-64 and ARM64 architectures.
• Linux/macOS requires Bash and curl; Windows requires PowerShell 5.1+.
• CLI installs to ~/.huawei/bin; configuration and state are stored in ~/.huawei/devbridge.
• Never commit ~/.huawei/devbridge to version control or share between users.
• Dynamic command adaptation — The scripts/devbridge_cmd.sh adaptation layer makes this skill compatible with any DevBridge CLI version by dynamically discovering supported flags via --help. No version pinning required.