Since sing-box 1.14.0

sing-box API

The sing-box API service is a gRPC server for observing and controlling the running sing-box instance.

It can be accessed by the sing-box graphical clients for iOS, macOS, and Android (via the Remote Control feature), or the sing-box dashboard.

The server also accepts gRPC-Web requests, including the WebSocket transport of @improbable-eng/grpc-web for bidirectional streaming methods.

Structure

{
  "type": "api",

  ... // Listen Fields

  "secret": "",
  "access_control_allow_origin": [],
  "access_control_allow_private_network": false,
  "dashboard": {
    "enabled": true,
    "path": "",
    "download_url": "",
    "http_client": "", // or {}
    "update_interval": ""
  },
  "tls": {}
}

Listen Fields

See Listen Fields for details.

Fields

secret

Secret for the API.

Clients authenticate with the standard authorization: Bearer <secret> gRPC metadata header.

If empty, authentication is disabled.

access_control_allow_origin

CORS allowed origins, * will be used if empty.

access_control_allow_private_network

Allow access from private network.

dashboard

Web dashboard downloaded and served over the API listener at /dashboard/; other browser requests are redirected to it.

The object can be replaced with a boolean value (equivalent to { "enabled": <bool> }), or with a string path (equivalent to { "enabled": true, "path": "<string>" }).

enabled

Enable the dashboard.

path

Directory the dashboard files are stored in.

dashboard in the working directory will be used by default.

If the directory is empty, the dashboard is downloaded and an .etag file is stored inside it to skip unchanged updates. A non-empty directory without an .etag file is served as-is and never updated automatically.

download_url

Download URL of the dashboard archive (zip).

https://github.com/SagerNet/sing-box-dashboard/archive/refs/heads/gh-pages.zip will be used by default.

http_client

HTTP client used to download the dashboard.

See HTTP Client Fields for details.

Not used when the dashboard directory contains user-provided files.

update_interval

Update interval of the dashboard.

1d will be used by default.

tls

TLS configuration, see TLS.