Experimental

The experimental block carries four loosely related feature areas: the persistent cache file, the Clash-compatible RESTful API, the V2Ray gRPC stats API, and the embedded pprof / runtime-debug endpoint.

Field	Type	Default	Allowed values	Description
`cache_file`	`*CacheFileOptions`	`(unset)`	`CacheFileOptions`	Persistent state cache.
`clash_api`	`*ClashAPIOptions`	`(unset)`	`ClashAPIOptions`	External controller compatible with Clash dashboards.
`v2ray_api`	`*V2RayAPIOptions`	`(unset)`	`V2RayAPIOptions`	gRPC stats service compatible with V2Ray clients.
`debug`	`*DebugOptions`	`(unset)`	`DebugOptions`	Embedded pprof endpoint and GC tuning.

Source: option/experimental.go:5-10 · pinned at v1.13.11 (553cfa1)

`cache_file`

Persistent on-disk cache for fakeip leases, selected-proxy memory, RDRC entries, and similar runtime state.

Field	Type	Default	Allowed values	Description
`enabled`	`bool`	`false`	`true \| false`	Turn the cache file on.
`path`	`string`	`cache.db`	`<file path>`	Where to store the cache database.
`cache_id`	`string`	`(unset)`	`<string>`	Namespace prefix in the same cache file. Useful when one cache file is shared by multiple sing-box instances.
`store_fakeip`	`bool`	`false`	`true \| false`	Persist the fakeip lease table.
`store_rdrc`	`bool`	`false`	`true \| false`	Persist Reject-DNS-Resolution Cache (rdrc) entries.
`rdrc_timeout`	`badoption.Duration`	`7d`	`<duration>`	How long rdrc entries stay valid in the cache.

Source: option/experimental.go:12-19 · pinned at v1.13.11 (553cfa1)

`clash_api`

A drop-in implementation of the Clash RESTful API. Compatible with metacubexd, Yacd, Clash Dashboard, and other Clash-API consumers.

Field	Type	Default	Allowed values	Description
`external_controller`	`string`	`(unset)`	`<host:port>`	RESTful API listen address.
`external_ui`	`string`	`(unset)`	`<dir path>`	Local directory served as the dashboard.
`external_ui_download_url`	`string`	`https://github.com/MetaCubeX/metacubexd/archive/refs/heads/gh-pages.zip`	`<URL>`	Tarball auto-downloaded when external_ui is empty.
`external_ui_download_detour`	`string`	`(direct)`	`<outbound tag>`	Outbound to use for the download.
`secret`	`string`	`(unset)`	`<bearer token>`	Bearer-token required for all API calls. Highly recommended.
`default_mode`	`string`	`rule`	`rule \| global \| direct \| <custom>`	Initial tunnel mode reported via the API. Custom values are accepted; non-standard dashboards ignore them.
`access_control_allow_origin`	`badoption.Listable[string]`	`[]`	`<origin>`	CORS allow-list for the API.
`access_control_allow_private_network`	`bool`	`false`	`true \| false`	Allow private-network preflight requests.

Source: option/experimental.go:21-42 · pinned at v1.13.11 (553cfa1)

Five additional fields (cache_file, cache_id, store_mode, store_selected, store_fakeip) are deprecated forwards into the cache_file block — keep them out of new configs.

`v2ray_api`

The V2Ray-compatible gRPC stats API. Useful if you have existing tooling (v2ray api stats query ...) you want to keep using.

Field	Type	Default	Allowed values	Description
`listen`	`string`	`(required)`	`<host:port>`	gRPC listen address for the StatsService.
`stats`	`*V2RayStatsServiceOptions`	`(unset)`	`V2RayStatsServiceOptions`	Counter selection.

Source: option/experimental.go:44-47 · pinned at v1.13.11 (553cfa1)

`v2ray_api.stats`

Field	Type	Default	Allowed values	Description
`enabled`	`bool`	`false`	`true \| false`	Turn the stats service on.
`inbounds`	`[]string`	`[]`	`<inbound tag>`	Inbound tags to count traffic for.
`outbounds`	`[]string`	`[]`	`<outbound tag>`	Outbound tags to count traffic for.
`users`	`[]string`	`[]`	`<user name>`	Per-user counters.

Source: option/experimental.go:49-54 · pinned at v1.13.11 (553cfa1)

`debug`

The Go-runtime tuning block. Most fields are direct knobs for the runtime and runtime/debug packages. The listen field exposes the standard net/http/pprof handlers.

Field	Type	Default	Allowed values	Description
`listen`	`string`	`(unset)`	`<host:port>`	pprof endpoint listen address (e.g. 127.0.0.1:6060).
`gc_percent`	`*int`	`(Go default)`	`<int> \| -1`	GOGC override. -1 disables garbage collection.
`max_stack`	`*int`	`(Go default)`	`<bytes>`	Per-goroutine stack ceiling.
`max_threads`	`*int`	`(Go default)`	`<int>`	GOMAXPROCS-style thread cap.
`panic_on_fault`	`*bool`	`false`	`true \| false`	Convert unrecoverable runtime faults into a panic with stack trace.
`trace_back`	`string`	`(Go default)`	`none \| single \| all \| system \| crash`	GOTRACEBACK setting.
`memory_limit`	`*byteformats.MemoryBytes`	`(unset)`	`<bytes/MiB/GiB>`	Soft memory cap; accepts plain numbers (bytes) or suffixed values like 256MiB.
`oom_killer`	`*bool`	`false`	`true \| false`	Crash the process when memory_limit is exceeded for too long.

Source: option/debug.go:5-14 · pinned at v1.13.11 (553cfa1)

Example

json

{
  "experimental": {
    "cache_file": {
      "enabled": true,
      "path": "cache.db",
      "store_fakeip": true
    },
    "clash_api": {
      "external_controller": "127.0.0.1:9090",
      "secret": "<random>",
      "external_ui": "/etc/sing-box/ui"
    },
    "debug": {
      "listen": "127.0.0.1:6060",
      "memory_limit": "256MiB"
    }
  }
}

Notes

The deprecated cache-related fields on clash_api (cache_file, cache_id, store_mode, store_selected, store_fakeip) still parse, but they emit warnings on load and will be removed in a future release. All five forward into the cache_file block.
debug.memory_limit accepts both plain numbers (bytes) and suffixed literals like "256MiB" or "2GiB", parsed by byteformats.MemoryBytes.

Source: option/experimental.go:5-54 · v1.13.11 (553cfa1)

Experimental ​

cache_file ​

clash_api ​

v2ray_api ​

v2ray_api.stats ​

debug ​

Example ​

Notes ​