sing-box/docs/configuration/shared/http-client.md

icon

icon
material/new-box

!!! question "Since sing-box 1.14.0"

Structure

A string or an object.

When string, the tag of a shared HTTP Client defined in top-level http_clients.

When object:

{
  "engine": "",
  "version": 0,
  "disable_version_fallback": false,
  "headers": {},

  ... // HTTP2 Fields

  "tls": {},

  ... // Dial Fields
}

Fields

engine

HTTP engine to use.

Values:

• go (default)
• apple
• cronet

apple uses NSURLSession, only available on Apple platforms.

!!! warning ""

Experimental only: due to the high memory overhead of both CGO and Network.framework,
do not use in hot paths on iOS and tvOS.

Supported fields:

• headers
• tls.server_name (must match request host)
• tls.insecure
• tls.min_version / tls.max_version
• tls.certificate / tls.certificate_path
• tls.certificate_public_key_sha256
• Dial Fields

Unsupported fields:

• version
• disable_version_fallback
• HTTP2 Fields
• QUIC Fields
• tls.engine
• tls.alpn
• tls.disable_sni
• tls.cipher_suites
• tls.curve_preferences
• tls.client_certificate / tls.client_certificate_path / tls.client_key / tls.client_key_path
• tls.fragment / tls.record_fragment
• tls.kernel_tx / tls.kernel_rx
• tls.ech
• tls.utls
• tls.reality

cronet uses Cronet, only available when sing-box is built with the with_naive_outbound tag.

Supported fields:

• version
• disable_version_fallback (version = 3 only)
• headers
• tls.server_name (must match request host)
• tls.certificate / tls.certificate_path
• tls.certificate_public_key_sha256
• tls.ech.config / tls.ech.config_path / tls.ech.query_server_name
• http2.stream_receive_window / http2.connection_receive_window
• quic.stream_receive_window / quic.connection_receive_window
• quic.idle_timeout
• Dial Fields

Unsupported fields:

• tls.engine
• tls.disable_sni
• tls.insecure
• tls.alpn
• tls.min_version / tls.max_version
• tls.cipher_suites
• tls.curve_preferences
• tls.client_certificate / tls.client_certificate_path / tls.client_key / tls.client_key_path
• tls.fragment / tls.record_fragment
• tls.kernel_tx / tls.kernel_rx
• tls.handshake_timeout
• tls.utls
• tls.reality
• http2.idle_timeout
• http2.keep_alive_period
• http2.max_concurrent_streams
• quic.keep_alive_period
• quic.initial_packet_size
• quic.disable_path_mtu_discovery
• quic.max_concurrent_streams

version

HTTP version.

Available values: 1, 2, 3.

2 is used by default.

When 3, HTTP2 Fields are replaced by QUIC Fields.

disable_version_fallback

Disable automatic fallback to lower HTTP version.

headers

Custom HTTP headers.

Host header is used as request host.

HTTP2 Fields

When version is 2 (default).

See HTTP2 Fields for details.

QUIC Fields

When version is 3.

See QUIC Fields for details.

TLS Fields

See TLS for details.

Dial Fields

See Dial Fields for details.