Services

services run background components that are neither inbounds nor outbounds: the sing-box API, a systemd-resolved replacement, a Shadowsocks server management API, a Tailscale DERP relay, a Hysteria realm server, USB/IP device sharing and a few helpers. The entry shape is the same flat envelope as everywhere else in the config — type / tag plus the selected type's own fields at the same level.

Envelope

Field	Type	Default	Allowed values	Description
type	string	—	api | resolved | ssm-api | hysteria-realm | derp | ccm | ocm | oom-killer | usbip-server | usbip-client	Service type. Selects which option struct the rest of the object is decoded into. Some types only exist in builds carrying their tag — see Notes.
tag	string	—	—	Unique name for this service, used in log lines.

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

Service types

Type	What it runs
api	The sing-box API: a gRPC / gRPC-Web server for observing and controlling the running instance — logs, outbound groups, Clash mode, connections. Used by the graphical clients' remote control, the sing-box Dashboard and the sing-box api command. See API service.
resolved	A drop-in replacement for systemd-resolved: a DNS stub listener (defaults to 127.0.0.53:53) that answers via sing-box DNS. Pairs with the resolved DNS server type.
ssm-api	The Shadowsocks Server Management API — an HTTP endpoint for creating and removing users on a running Shadowsocks inbound.
hysteria-realm	Rendezvous server for Hysteria2 NAT traversal. See the realm fields on Hysteria2. See Hysteria realm.
derp	An embedded Tailscale DERP relay server. See Tailscale.
ccm / ocm	Claude Code Multiplexer / OpenAI Codex Multiplexer: share a local Claude Code or OpenAI Codex subscription with remote clients through custom tokens, with OAuth handled on the local machine.
oom-killer	Out-of-memory guard (memory_limit, safety_margin, check intervals) for memory-constrained deployments.
usbip-server / usbip-client	Export / import USB devices over USB/IP. See USB/IP.

Minimal example

{
  "services": [
    {
      "type": "resolved",
      "tag": "resolved",
      "listen": "127.0.0.53",
      "listen_port": 53
    }
  ]
}

Notes

• resolved embeds the same ListenOptions as inbounds; when omitted, listen defaults to 127.0.0.53 and listen_port to 53.
• ssm-api takes a servers map (path → Shadowsocks inbound tag) and an optional cache_path.
• Build tags gate availability: derp needs with_tailscale, ccm needs with_ccm, ocm needs with_ocm, hysteria-realm needs with_quic, and usbip-server / usbip-client need with_usbip (Linux, Windows, and macOS with CGO). api, resolved, ssm-api and oom-killer are always compiled in. Official release binaries include all of these tags.
• api embeds ListenOptions. Clients authenticate with authorization: Bearer <secret>; an empty secret disables authentication, so set one on any non-loopback listener. The optional dashboard block downloads the sing-box Dashboard and serves it at /dashboard/ on the same listener.
• hysteria-realm only carries signaling: a Hysteria2 server behind NAT registers its STUN-discovered addresses, clients look them up and hole-punch a direct QUIC connection, and proxy traffic then flows directly between them.
• usbip-server listens on port 3240 by default and stays interoperable with standard USB/IP clients; usbip-client requires a sing-box (sing-usbip) server.
• An unregistered type fails at startup with "unknown service type".

Cross-core notes

• Xray-core has no service list; the closest analogues are the API and Metrics blocks, which spawn management listeners from dedicated config keys.
• mihomo exposes management through the external controller rather than configurable background services.

Source: option/service.go:18-22 · v1.14.2 (af6e64c)