API service — sing-box

The api service is a gRPC server for observing and controlling the running sing-box instance: service status, logs, outbound groups (selection and URL tests), Clash mode, connection tracking, and tools such as network-quality and STUN tests or Tailscale operations. It exposes the same interface the graphical clients use locally, so their Remote Control feature, the sing-box Dashboard web client and the sing-box api command can all drive a remote instance. The listener also accepts gRPC-Web (including the WebSocket transport of the improbable-eng gRPC-Web client for streaming calls), so a browser can talk to it directly.

Options

type: "api" under services[]:

Field	Type	Default	Allowed values	Description
secret	string	(empty)	<string>	Shared secret. Clients send it as the gRPC metadata header authorization: Bearer <secret>. Empty disables authentication entirely, so always set one on a listener other hosts can reach.
access_control_allow_origin	badoption.Listable[string]	*	<origin> | …	CORS allowed origins for browser (gRPC-Web) clients such as the sing-box Dashboard. Empty means *.
access_control_allow_private_network	bool	false	true | false	Answer Private Network Access preflights (Access-Control-Allow-Private-Network), so a page served from a public origin — such as the hosted Dashboard — may call an API listening on a private or loopback address.
dashboard	*APIDashboardOptions	(disabled)	true | false | <directory path> | APIDashboardOptions	Serve the sing-box Dashboard at /dashboard/ on the same listener; other browser requests are redirected there. true equals { "enabled": true }, and a string is shorthand for { "enabled": true, "path": "<string>" }.

Source: option/api.go:11-18 · pinned at v1.14.2 (af6e64c)

The service also embeds ListenOptions (listen, listen_port, … — see Inbounds) and an inbound tls block (see TLS). There is no default port, so set listen_port explicitly.

dashboard

Field	Type	Default	Allowed values	Description
enabled	bool	false	true | false	Turn the dashboard on.
path	string	dashboard	<directory path>	Directory holding the dashboard files, relative to the working directory. An empty directory is filled by download and tracked with an .etag file; a non-empty directory without .etag is served as-is and never updated.
download_url	string	(gh-pages archive)	<URL>	Zip archive the dashboard is downloaded from. Defaults to the gh-pages branch archive of the sing-box-dashboard repository on GitHub.
http_client	*HTTPClientOptions	(default client)	<http_clients tag> | HTTPClientOptions	HTTP client used for the download: an inline object or the tag of an http_clients entry. Unused when the directory holds user-provided files.
update_interval	badoption.Duration	1d	<duration>	How often to check the download URL for a newer dashboard archive.

Source: option/api.go:20-26 · pinned at v1.14.2 (af6e64c)

The sing-box api command

sing-box api is a command-line client for this service with the operations the graphical clients offer — status, logs, outbound groups, Clash mode, connections, network-quality and STUN tests, Tailscale, OpenVPN / OpenConnect authentication, USB/IP and more. Point it at the service with --url (or $BOX_API_URL; http:// is assumed when no scheme is given) and --secret (or $BOX_API_SECRET).

Minimal example

{
  "services": [
    {
      "type": "api",
      "tag": "api",
      "listen": "127.0.0.1",
      "listen_port": 9091,
      "secret": "change-me",
      "dashboard": true
    }
  ]
}

sing-box api --url 127.0.0.1:9091 --secret change-me status

With dashboard: true, opening http://127.0.0.1:9091/ in a browser redirects to the Dashboard.

Notes

• An empty secret means anyone who can reach the port can read logs, switch outbound groups and close connections. Keep the listener on loopback, or set a secret (and tls) before exposing it.
• Without tls the listener speaks HTTP/1.1 and cleartext HTTP/2 (h2c); with tls, h2 and http/1.1 are added to the ALPN list automatically.
• The dashboard is downloaded when the service starts and re-checked every update_interval. A directory that already contains files but no .etag is treated as user-provided: it is served as-is and never overwritten.
• The service needs no build tag.
• The Clash-compatible REST API is a separate feature, experimental.clash_api; see Experimental.

Cross-core notes

• Xray-core exposes a gRPC API (api.services such as HandlerService and StatsService), reached through a dedicated inbound plus a routing rule. It has no bundled dashboard.
• mihomo uses the Clash-compatible REST external controller, optionally with a web UI — the same API family as sing-box's experimental.clash_api, not this gRPC service.

Source: option/api.go:11-26 · v1.14.2 (af6e64c)