> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobileboost.io/llms.txt
> Use this file to discover all available pages before exploring further.
# mb-local reference
> Commands, flags, environment variables, and exit codes for the MobileBoost Local binary
Complete reference for `mb-local`. For a walkthrough, start with
[Test against internal environments](/test-agent/local-testing).
## 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`
```bash theme={null}
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:
```bash theme={null}
mb-local status --tunnel-name my-tunnel --json
```
## Running as a daemon
```bash theme={null}
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/.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:
```json theme={null}
{
"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.