mb-local reference

Complete reference for mb-local. For a walkthrough, start with Test against internal environments.

Commands

Command	Description
`mb-local [flags]`	Start a tunnel in the foreground. Stop it with `Ctrl+C`
`mb-local --daemon start [flags]`	Start a tunnel in the background and return once it is connected
`mb-local --daemon stop --tunnel-name NAME`	Stop a background tunnel
`mb-local status`	Show a running tunnel’s state
`mb-local doctor`	Diagnose connectivity from this machine
`mb-local network-requirements`	Print the request to send your network team
`mb-local reap`	Clear state files left by tunnels that already exited
`mb-local version`	Print the version

Flags

Tunnel

Flag	Default	Description
`--key KEY`	env	Your MobileBoost API key, the same one used for the rest of the API. Prefer the environment variable so it stays out of logs
`--tunnel-name NAME`	derived	Tunnel identity. Must be unique among connected tunnels. Derived from CI variables or your hostname when omitted
`--force`	off	Replace an existing tunnel with the same name instead of failing
`--wait-for-ready DUR`	off	Block until the tunnel can carry traffic, then keep running. For example `60s`
`--links N`	`4`	Number of parallel connections. Raise it for tunnels serving many concurrent sessions
`--dial-timeout DUR`	`15s`	How long to wait when connecting to one of your internal hosts

Host rules

Flag	Description
`--only-hosts LIST`	Comma-separated hosts this tunnel may reach. Everything else leaves the device over its normal internet connection
`--exclude-hosts LIST`	Hosts this tunnel may never reach. Wins over `--only-hosts`
`--force-local`	Route all device traffic through the tunnel, not just matching hosts

Rule syntax:

Rule	Matches
`acme.internal`	that exact host
`*.acme.internal`	any subdomain, but not the apex
`.acme.internal`	the apex and every subdomain
`10.0.0.0/8`	any address in that range
`staging.acme.io:8443`	that host on that port only
`[fd00::1]:5432`	an IPv6 literal, which must be bracketed when a port is given
`mb-local.net`	the machine running `mb-local`, mapped back to `127.0.0.1` there

--force-local sends every request the device makes through your network, including traffic to public services. It is useful when you need the app’s outbound IP to be yours, but it makes the whole device depend on your tunnel. Your administrator must enable it for your organisation before it can be used.

Corporate networks

Flag	Description
`--proxy-host HOST`	Corporate proxy to reach MobileBoost through
`--proxy-port PORT`	Proxy port. Defaults to `3128`
`--proxy-user USER`	Proxy username, for proxies that require authentication
`--proxy-pass PASS`	Proxy password
`--no-proxy-discovery`	Ignore system and environment proxy settings, and connect directly
`--ca-cert PATH`	Additional root CA. Needed when a TLS-inspecting proxy signs connections with its own certificate
`--transport auto\|wss`	How the tunnel is carried. Leave on `auto`

mb-local finds your proxy automatically from HTTPS_PROXY and NO_PROXY, and from system settings on macOS. The flags are for when that guess is wrong.

Proxy auto-config (PAC) files are detected but not yet evaluated. If your machine uses one, mb-local tells you so and asks you to pass the proxy it selects with --proxy-host and --proxy-port.

Output

Flag	Default	Description
`--verbose N`	`1`	Verbosity from `0` (warnings only) to `3`
`--log-file PATH`	stderr	Write logs to a file
`--log-format text\|json`	`text`	Use `json` for structured log collection
`--api-addr ADDR`	random loopback port	Address of the local status API

Environment variables

Every common flag has an environment variable. Flags win when both are set.

Variable	Equivalent flag
`MOBILEBOOST_API_KEY`	`--key`
`MB_TUNNEL_NAME`	`--tunnel-name`
`MB_ONLY_HOSTS`	`--only-hosts`
`MB_EXCLUDE_HOSTS`	`--exclude-hosts`
`MB_PROXY_HOST`, `MB_PROXY_PORT`, `MB_PROXY_USER`, `MB_PROXY_PASS`	the `--proxy-*` flags
`MB_CA_CERT`	`--ca-cert`
`MB_TRANSPORT`	`--transport`
`MB_LOG_FORMAT`	`--log-format`
`MB_LOCAL_HOME`	Where state files and daemon logs are kept. Defaults to `~/.mb-local`

Exit codes

Code	Meaning
`0`	Clean exit
`10`	Access key rejected
`11`	Cannot reach MobileBoost
`12`	Tunnel could not be established
`13`	A tunnel with this name is already connected
`14`	Requested host rules are not permitted for your organisation
`15`	The key is valid but lacks the `tunnel:connect` scope
`20`	Your organisation’s tunnel limit is reached
`21`	The tunnel was revoked by an administrator
`22`	This binary is older than the minimum supported version
`64`	Invalid configuration, such as a malformed host rule

Codes 10, 13, 14, 15, 20, and 22 will not succeed on retry. The others may.

Reading `status`

mb-local status --tunnel-name my-tunnel

tunnel      my-tunnel (tun_4kd8xz2m9qwerty1)
state       connected, 4/4 links up
org         acme
relay       wss://relay-eu.mobileboost.io/v1/tunnel relay-eu-3
egress      system proxy proxy.corp:8080
policy      allow=*.acme.internal,10.0.0.0/8
org policy  allow=*.acme.internal deny=secrets.acme.internal
uptime      14m22s (0 reconnects)
rtt         38ms
sessions    2 attached
traffic     147 dials, 0 errors, 3 denied, 2.1M up / 18.4M down bytes

Field	What it tells you
`state`	`connected` with all links up is healthy. A number below the target means connections are being retried
`egress`	How the binary is reaching MobileBoost. Useful for confirming a proxy was picked up
`policy`	The rules you configured
`org policy`	Rules your administrator set centrally. These apply in addition to yours
`sessions`	How many test sessions are currently using this tunnel
`denied`	Requests refused by policy. A non-zero count usually means a host is missing from `--only-hosts`
`reconnects`	How often the tunnel has had to reconnect. Repeated growth points at an unstable network

Add --json for machine-readable output:

mb-local status --tunnel-name my-tunnel --json

Running as a daemon

mb-local --daemon start --tunnel-name my-tunnel --only-hosts '*.acme.internal'
mb-local status --tunnel-name my-tunnel
mb-local --daemon stop --tunnel-name my-tunnel

--daemon start returns only once the tunnel is connected, so the next command in a script can rely on it. Logs go to ~/.mb-local/<tunnel-name>.log. If a machine is killed before a tunnel is stopped, its state file is left behind. mb-local reap clears the ones whose process is gone.

Configuring a tunnel for a test run

Name the tunnel in the execution payload:

{
  "organisationId": "org123",
  "uploadId": "BUILD_ID",
  "tags": ["critical"],
  "tunnelName": "my-tunnel"
}

Every device in the run is pointed at that tunnel. If the tunnel is not connected when the run starts, the run fails immediately with a message naming the tunnel, rather than starting and timing out on every request.

Getting started

Test definitions

Test execution

Test reports

Commands

Flags

Tunnel

Host rules

Corporate networks

Output

Environment variables

Exit codes

Reading `status`

Running as a daemon

Configuring a tunnel for a test run

​Commands

​Flags

​Tunnel

​Host rules

​Corporate networks

​Output

​Environment variables

​Exit codes

​Reading status

​Running as a daemon

​Configuring a tunnel for a test run

Commands

Flags

Tunnel

Host rules

Corporate networks

Output

Environment variables

Exit codes

Reading `status`

Running as a daemon

Configuring a tunnel for a test run