### Configure SCRIPT rules

Source: https://stash.wiki/en/rules/rule-types

Example configuration for intercepting specific traffic patterns using script shortcuts.

```yaml
rules:
  - SCRIPT,quic,REJECT
  - SCRIPT,udp-cn,ProxyToCN
 
script:
  shortcuts: # Can be referenced in rules
    quic: network == 'udp' and dst_port == 443 # Matches QUIC protocol
    udp-cn: network == 'udp' and geoip(dst_ip if dst_ip != '' else resolve_ip(host)) == 'CN' # Matches UDP to CN
    instagram-quic: network == 'udp' and dst_port == 443 and match_geosite('instagram') # Matches Instagram's QUIC
```

--------------------------------

### URL-REGEX Rule Example

Source: https://stash.wiki/en/en/rules/rule-types

Matches URLs using regular expressions. This example matches requests to Amazon Video or related pages.

```text
URL-REGEX,^https?://www.amazon.com/(Amazon-Video|gp/video)/,PROXY
```

--------------------------------

### Configure HTTP Rewriting Script

Source: https://stash.wiki/en/script/rewrite-requests

Example configuration for matching a URL and applying a response script. Ensure the script provider is correctly defined.

```yaml
http:
  script:
    - match: url-you-want-to-match
      name: your-fancy-script
      type: response # request / response
      require-body: true
      timeout: 20
      argument: ''
      binary-mode: false
      max-size: 1048576 # 1MB

script-providers:
  your-fancy-script:
    url: https://your-fancy-script.com/your-fancy-script.js
    interval: 86400

```

--------------------------------

### SCRIPT Rule Example for QUIC

Source: https://stash.wiki/en/en/rules/rule-types

Use this rule to match and reject QUIC protocol requests. Ensure the 'script' section is configured to define the 'quic' shortcut.

```yaml
rules:
  - SCRIPT,quic,REJECT
```

--------------------------------

### AND Logical Rule Example

Source: https://stash.wiki/en/en/rules/rule-types

Combines multiple rules to ensure all conditions are met. The 'no-resolve' parameter can be used in sub-rules to prevent DNS lookups.

```text
AND,((#Rule1), (#Rule2), (#Rule3)...),PROXY
```

```text
AND,((IP-CIDR,192.168.1.110,no-resolve),   (DOMAIN-SUFFIX,example.com), (DOMAIN-KEYWORD, xxx)), DIRECT
```

--------------------------------

### USER-AGENT Rule Example

Source: https://stash.wiki/en/en/rules/rule-types

Matches network requests based on the User-Agent header. Wildcards can be used for partial string matching.

```text
USER-AGENT,AppleNews*,PROXY
```

--------------------------------

### OR Logical Rule Example

Source: https://stash.wiki/en/en/rules/rule-types

Satisfies the rule if any of the listed sub-rules are met. This is useful for creating flexible matching conditions.

```text
OR,((#Rule1), (#Rule2), (#Rule3)...),PROXY
```

--------------------------------

### Override BiliBili CDN Configuration

Source: https://stash.wiki/en/configuration/override

This example demonstrates overriding HTTP force-http-engine and url-rewrite settings for BiliBili, and defining a script shortcut.

```yaml
name: Redirect BiliBili MCDN / PCDN to Regular CDN
desc: Cheers to a smoother BiliBili loading experience! 🍻

http:
  force-http-engine:
    - 'upos-*.bilivideo.com:80'
    - '*:4480'
    - '*:9102'
  url-rewrite:
    - https?:\]\/\/(.*):4480\/upgcxcode http://upos-sz-mirrorcos.bilivideo.com/upgcxcode 302
    - https?:\]\/\/(.*):9102\/upgcxcode http://upos-sz-mirrorcos.bilivideo.com/upgcxcode 302
    - https?:\/\/upos-.*-.*oss\d*\.bilivideo\.com\/upgcxcode http://upos-sz-mirrorcos.bilivideo.com/upgcxcode 302
    - https?:\/\/upos-sz-mirror(?!cos\.).*bilivideo\.com\/upgcxcode http://upos-sz-mirrorcos.bilivideo.com/upgcxcode 302
    # alternative:
    # upos-sz-mirrorhw.bilivideo.com
    # upos-sz-mirrorcos.bilivideo.com
    # upos-sz-mirrorcoso1.bilivideo.com
    # upos-sz-mirrorcoso2.bilivideo.com
    # upos-sz-mirrorbs.bilivideo.com
    # upos-sz-mirrorali.bilivideo.com
script:
  shortcuts:
    bilibili-quic: network == 'udp' and geoip(dst_ip) == 'CN' and dst_port == 3478
rules:
  - SCRIPT,bilibili-quic,REJECT

```

--------------------------------

### Override DNS Nameservers with CloudFlare

Source: https://stash.wiki/en/configuration/override

This example shows how to use the `#!replace` syntax to completely replace the default and custom nameservers with CloudFlare's DNS over HTTPS endpoints.

```yaml
name: Use Only CloudFlare DNS
dns:
  # This will completely replace the original default-nameserver
  default-nameserver: #!replace
    - system
    - 223.5.5.5
    - 1.0.0.1
  # This will completely replace the original nameserver
  nameserver: #!replace
    - https://1.0.0.1/dns-query # CF IPv4
    - https://[2606:4700:4700::1111]/dns-query # CF IPv6

```

--------------------------------

### Basic HTTP GET Request

Source: https://stash.wiki/en/script/syntax-and-interface

Use this method to perform a simple HTTP GET request. Logs any errors or the received data.

```javascript
$httpClient.get('http://httpbin.org/get', (error, response, data) => {
  if (error) {
    console.log(error)
  } else {
    console.log(data)
  }
})
```

--------------------------------

### Control Stash Application

Source: https://stash.wiki/en/faq/url-schema

Commands to start, stop, or toggle the Stash application using different URL schemas.

```APIDOC
## Control Stash Application

### Description
Control the Stash application's running state.

### Start Stash
- `stash://start`
- `clash://start`
- `https://link.stash.ws/start`

### Stop Stash
- `stash://stop`
- `clash://stop`
- `https://link.stash.ws/stop`

### Toggle On/Off Stash
- `stash://toggle`
- `clash://toggle`
- `https://link.stash.ws/toggle`
```

--------------------------------

### NOT Logical Rule Example

Source: https://stash.wiki/en/en/rules/rule-types

Negates a specific rule, matching traffic that does not satisfy the condition. Logical rules can be nested, as shown in the example combining NOT with AND.

```text
NOT,((#Rule1)),PROXY
```

```text
AND,((NOT,((SRC-IP,192.168.1.110))),(DOMAIN,example.com)),DIRECT
```

--------------------------------

### YAML Merging and Replacement Example

Source: https://stash.wiki/en/configuration/override

Illustrates how Stash merges dictionaries recursively and replaces arrays when using the `#!replace` directive.

```yaml
# config.yaml
dict:
  k1: true
  k2: 1
  k3:
    - 1
    - 2
    - 3
  k4:
    - 1
    - 2
    - 3

```

```yaml
# override file
key: value
dict:
  k3:
    - 0
  k4: #!replace
    - 1
  k5: null

```

```yaml
# after override
key: value
dict:
  k1: true
  k2: 1
  k3:
    - 0
    - 1
    - 2
    - 3
  k4:
    - 1
  k5: null

```

--------------------------------

### SCRIPT Rule Example for UDP to China

Source: https://stash.wiki/en/en/rules/rule-types

This rule matches UDP traffic destined for mainland China. It relies on the 'geoip' function and the 'udp-cn' shortcut defined in the script configuration.

```yaml
rules:
  - SCRIPT,udp-cn,ProxyToCN
```

--------------------------------

### Import Configuration File

Source: https://stash.wiki/en/faq/url-schema

Instructions for importing configuration files using different URL schemas. The URL must be URL-encoded when using `stash://` or `clash://`.

```APIDOC
## Import Configuration File

### Description
Import a configuration file into Stash.

### Methods
- `stash://install-config?url=${url-encoded}`
- `clash://install-config?url=${url-encoded}`
- `https://link.stash.ws/install-config/example.com/stash.yaml`

### Notes
- For `stash://` and `clash://`, the `url` parameter must be URL-encoded.
- For `https://link.stash.ws`, the URL format is `https://link.stash.ws/install-config/<remote-url>`, where `<remote-url>` is the URL to the configuration file (e.g., `example.com/stash.yaml`). This URL does not need to be encoded and does not include the schema.
```

--------------------------------

### Configure a Stash Proxy Group with Filtering

Source: https://stash.wiki/en/proxy-protocols/proxy-groups

Use include-all to reference all available proxies and apply a filter to select specific nodes based on regular expressions.

```yaml
proxy-groups:
  - name: my-hongkong-group
    type: select
    include-all: true # Reference all proxies & proxy-providers
    filter: 'HK|Hong Kong' # Filter proxies with the keywords HK or Hong Kong
```

--------------------------------

### Multi-Hop Proxy Chains

Source: https://stash.wiki/en/proxy-protocols/dialer-proxy

Demonstrates building a multi-hop chain by nesting dialer-proxy assignments across multiple proxies.

```yaml
proxies:
  - name: ss-up
    type: ss
    server: 1.2.3.4
    port: 8388
    cipher: aes-128-gcm
    password: example
 
  - name: trojan-mid
    type: trojan
    server: mid.example.com
    port: 443
    password: <password>
    dialer-proxy: ss-up
 
  - name: vmess-end
    type: vmess
    server: end.example.com
    port: 443
    uuid: <uuid>
    tls: true
    dialer-proxy: trojan-mid
```

--------------------------------

### Configure Proxy Delay Testing Parameters

Source: https://stash.wiki/en/proxy-protocols/proxy-benchmark

Define benchmark URL and timeout settings within a proxy configuration block. Use HTTP protocol for the benchmark URL to ensure compatibility.

```yaml
proxies:
  - name: your-proxy
    type: ss
    server: server
    port: 443
    benchmark-url: http://www.apple.com # It is recommended to use only HTTP protocol
    benchmark-timeout: 5 # Delay test timeout, in seconds
```

--------------------------------

### Configure Rule Providers and Rules

Source: https://stash.wiki/en/rules/rule-set

Define external rule sources in the rule-providers section and apply them within the rules list. Use domain or ipcidr behaviors for optimized performance.

```yaml
rule-providers:
  proxy-domain:
    behavior: domain # Using domain-type rule sets can improve matching efficiency
    format: yaml # Use YAML format for rule sets
    url: https://cdn.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/proxy.txt
    interval: 86400
 
  cn-cidr:
    behavior: ipcidr # Using ipcidr-type rule sets can improve matching efficiency
    format: text # Use text format for rule sets
    url: https://cdn.jsdelivr.net/gh/17mon/china_ip_list@master/china_ip_list.txt
    interval: 86400
 
rules:
  - RULE-SET,proxy-domain,Proxy
  - RULE-SET,cn-cidr,DIRECT,no-resolve # ipcidr-type rule sets support the no-resolve parameter
```

--------------------------------

### Subscribe to Service Provider Configuration

Source: https://stash.wiki/en/features/service-provider-subscription

Add this comment at the top of your configuration file to enable periodic fetching of updates from a service provider. The check interval is 12 hours by default.

```yaml
#SUBSCRIBED https://proxy.service/stash/config
```

--------------------------------

### Remove Stash Helper via Terminal

Source: https://stash.wiki/en/faq/stash-mac-helper

Use this command to remove the existing helper tool when installation fails. Requires administrative privileges.

```bash
sudo rm -rf /Library/PrivilegedHelperTools/ws.stash.app.mac.daemon.helper
```

--------------------------------

### Shortcut for Remote Proxy Sets

Source: https://stash.wiki/en/proxy-protocols/proxy-providers

Use `use-url` in `proxy-groups` for a quick way to reference remote proxy sets. Update time and name cannot be specified when using this shortcut.

```yaml
proxy-groups:
  - name: auto
    type: url-test
    interval: 300
    use-url:
      - https://raw.githubusercontent.com/STASH-NETWORKS-LIMITED/stash-example/main/config.yaml
```

--------------------------------

### Configure Juicity Proxy

Source: https://stash.wiki/en/proxy-protocols/proxy-types

Configuration template for the Juicity proxy protocol.

```yaml
name: juicity
type: juicity
server: server
port: 443
uuid: d0529668-8835-11ec-a8a3-0242ac120002
password: your_password
skip-cert-verify: true
sni: ''
alpn:
  - h3
```

--------------------------------

### Configure Custom Hosts

Source: https://stash.wiki/en/features/dns-server

Maps domain names to specific IP addresses, supporting wildcard patterns.

```yaml
# Support wildcard domain names (e.g., *.clash.dev, *.foo.*.example.com)
# Non-wildcard domain names take precedence over wildcard domain names (e.g., foo.example.com > *.example.com > .example.com)
# Note: The effect of +.foo.com is equivalent to .foo.com and foo.com
hosts:
  '*.clash.dev': 127.0.0.1
  '.dev': 127.0.0.1
  'alpha.clash.dev': ::1
```

--------------------------------

### Configure Tile Panel in Stash

Source: https://stash.wiki/en/script/tile

Define the script name, update interval, and default UI properties in the configuration file.

```yaml
tiles:
  - name: your-fancy-script
    interval: 600
    title: 'Awesome Tile'
    content: 'This is Super Cool'
    icon: 'theatermasks.circle.fill' # or https://stash.ws/amazing.png
    backgroundColor: '#663399'
 
script-providers:
  your-fancy-script:
    url: https://your-fancy-script.com/your-fancy-script.js
    interval: 86400
```

--------------------------------

### Reload Stash Helper Daemon

Source: https://stash.wiki/en/faq/stash-mac-helper

Use this command to manually load the helper daemon configuration. Ignore 'service already loaded' errors if they occur.

```bash
sudo /bin/launchctl load -w /Library/LaunchDaemons/ws.stash.app.mac.daemon.helper.plist
```

--------------------------------

### Basic Scripting Methods

Source: https://stash.wiki/en/script/syntax-and-interface

Provides an overview of fundamental script properties and functions available within the Stash scripting environment.

```APIDOC
## Basic Scripting Methods

### Description
Access script properties, environment variables, arguments, and control script execution.

### Methods
- `$script.name`: (String) The name of the script.
- `$script.type`: (String) The type of the script (e.g., `request`, `response`, `tile`).
- `$script.startTime`: (Number) The timestamp when the script started running.
- `$environment["stash-build"]`: (String) The Stash Build number.
- `$environment["stash-version"]`: (String) The Stash version number.
- `$environment.language`: (String) The language Stash is running in.
- `$environment.system`: (String) The operating system Stash is running on (iOS / macOS).
- `$argument`: (Any) The parameters passed to the script during execution.

### Functions
- `$done(value)`: Ends the script execution and releases resources. It's mandatory to call this function at the end of every script.
- `$notification.post(title, subtitle, body)`: Sends an iOS notification with the specified title, subtitle, and body.
- `console.log(value)`: Outputs a log message. Script logs are saved to a separate file.
- `setTimeout(callback, delay)`: Schedules a function (`callback`) to be executed after a specified delay (in milliseconds).
```

--------------------------------

### Configure Advanced Mock Responses

Source: https://stash.wiki/en/http-engine/rewrite

Provides static responses with custom headers, supporting both plain text and base64 encoded content.

```yaml
http:
  mock:
    - match: ^https?://example.stash\.ws/json
      text: '{}'
      status-code: 200
      headers:
        Content-Type: application/json
    - match: ^https?://example.stash\.ws/base64
      base64: 'eyJ0ZXN0IjogdHJ1ZX0='
      status-code: 200
      headers:
        Content-Type: application/json
```

--------------------------------

### ShadowsocksR Configuration

Source: https://stash.wiki/en/proxy-protocols/proxy-types

Basic configuration for ShadowsocksR. Supported encryption and obfuscation methods are detailed in the documentation.

```yaml
name: ssr
type: ssr
server: server
port: 443
cipher: chacha20-ietf
password: 'password'
obfs: ''
protocol: ''
obfs-param: ''
protocol-param: ''
```

--------------------------------

### V2ray-Plugin Configuration for Shadowsocks

Source: https://stash.wiki/en/proxy-protocols/proxy-types

Configure the v2ray-plugin for Shadowsocks to carry traffic over WebSocket. Supports TLS, custom hosts, paths, and headers.

```yaml
plugin: v2ray-plugin
plugin-opts:
  mode: websocket # Currently QUIC is not supported
  tls: true # wss
  skip-cert-verify: true # Don't verify certificate
  host: bing.com
  path: '/'
  headers: # Custom request headers
    key: value
```

--------------------------------

### Import Icon Set

Source: https://stash.wiki/en/faq/url-schema

Instructions for importing icon sets using different URL schemas. The URL must be URL-encoded when using `stash://` or `clash://`.

```APIDOC
## Import Icon Set

### Description
Import an icon set into Stash.

### Methods
- `stash://install-icon-set?url=${url-encoded}`
- `clash://install-icon-set?url=${url-encoded}`
- `https://link.stash.ws/install-icon-set/example.com/stash.json`

### Notes
- For `stash://` and `clash://`, the `url` parameter must be URL-encoded.
- For `https://link.stash.ws`, the URL format is `https://link.stash.ws/install-icon-set/<remote-url>`, where `<remote-url>` is the URL to the icon set file (e.g., `example.com/stash.json`). This URL does not need to be encoded and does not include the schema.
```

--------------------------------

### Shadow-TLS Plugin Configuration for Shadowsocks

Source: https://stash.wiki/en/proxy-protocols/proxy-types

Configure the shadow-tls plugin for Shadowsocks to perform a real TLS handshake. Supports specific versions, passwords, and hosts.

```yaml
plugin: shadow-tls
plugin-opts:
  password: singalongsong
  host: weather-data.apple.com
  skip-cert-verify: false # Don't verify certificate
  version: 3 # Only supports version 2 and 3
```

--------------------------------

### Configure Shell Proxy Settings

Source: https://stash.wiki/en/features/provide-proxy-to-lan-device

Use these commands to configure your shell to use the Stash proxy running on a local network device. Ensure 'Allow LAN connections' is enabled in Stash.

```bash
export https_proxy=http://192.168.1.10:7890
export http_proxy=http://192.168.1.10:7890
export all_proxy=socks5h://192.168.1.10:7890
```

--------------------------------

### Configure WireGuard Proxy

Source: https://stash.wiki/en/proxy-protocols/proxy-types

Configuration template for WireGuard. Note that performance may be lower than other protocols due to user-space conversion.

```yaml
name: wireguard
type: wireguard
server: server # domain is supported
port: 51820
ip: 10.8.4.8
# ipv6: fe80::e6bf:faff:fea0:9fae # optional
private-key: 0G6TTWwvgv8Gy5013/jv2GttkCLYYaNTArHV0NdNkGI= # client private key
public-key: 0ag+C+rINHBnvLJLUyJeYkMWvIAkBjQPPObicuBUn1U= # peer public key
# preshared-key: # optional
dns: [1.0.0.1, 223.6.6.6] # optional
# mtu: 1420 # optional
# reserved: [0, 0, 0] # optional
# keepalive: 45 # optional
```

--------------------------------

### Configure force-http-engine in YAML

Source: https://stash.wiki/en/http-engine/force-http-engine

Define the host and port patterns that should be intercepted and handled by the HTTP engine.

```yaml
http:
  # Force the use of Stash engine to handle TCP connections using HTTP protocol
  # Captured connections can use advanced features such as rewriting and scripts
  force-http-engine:
    - '*:80'
    - '*:4480' # BiliBili CDN
    - '*:9102' # BiliBili CDN
```

--------------------------------

### Basic Dialer Proxy Configuration

Source: https://stash.wiki/en/proxy-protocols/dialer-proxy

Configures a WireGuard proxy to route its connection through a Shadowsocks proxy.

```yaml
proxies:
  - name: ss1
    type: ss
    server: 1.2.3.4
    port: 8388
    cipher: aes-128-gcm
    password: example
 
  - name: wg-warp
    type: wireguard
    server: 162.159.195.5
    port: 2408
    private-key: <private-key>
    public-key: <public-key>
    ip: 172.16.0.2
    dns:
      - 1.1.1.1
    dialer-proxy: ss1
```

--------------------------------

### Configure TUIC v5 and v4 Proxies

Source: https://stash.wiki/en/proxy-protocols/proxy-types

Configuration templates for TUIC v5 and v4 protocols. Ensure the server has the --alpn h3 parameter enabled.

```yaml
name: tuic-v5
type: tuic
server: server
port: 443
version: 5
uuid: d0529668-8835-11ec-a8a3-0242ac120002 # for v5
password: your_password # for v5
skip-cert-verify: true
sni: ''
alpn:
  - h3
```

```yaml
name: tuic-v4
type: tuic
server: server
port: 443
version: 4
token: 'your_token' # for v4
skip-cert-verify: true
sni: ''
alpn:
  - h3
```

--------------------------------

### SCRIPT Rule Configuration

Source: https://stash.wiki/en/rules/rule-types

Defines how to use Python-like expressions to match network traffic based on connection metadata and helper functions.

```APIDOC
## SCRIPT

### Description
Matches requests through a Python expression. The expression must return a Boolean value. Execution errors are ignored.

### Available Variables
- **network** (string) - tcp or udp
- **host** (string) - Target host, may be empty
- **dst_ip** (string) - Destination IP, may be empty
- **dst_port** (number) - Destination port
- **src_ip** (string) - Source IP (gateway mode only)
- **src_port** (number) - Source port (gateway mode only)

### Available Functions
- **resolve_ip(host: str)** - Resolves host to IP
- **in_cidr(ip: str, cidr: str)** - Checks if IP is in CIDR
- **geoip(ip: str)** - Returns country code for IP
- **ipasn(ip: str)** - Returns ASN for IP
- **match_provider(name: str)** - Matches provider
- **match_geosite(name: str)** - Matches geosite

### Example
```yaml
script:
  shortcuts:
    quic: network == 'udp' and dst_port == 443
```
```

--------------------------------

### Configure UDP Nameserver for Proxies

Source: https://stash.wiki/en/proxy-protocols/proxy-types

Specify DNS server addresses for UDP proxy configurations. Only UDP protocol is supported.

```yaml
name: proxy
type: ss
udp-nameserver: ['8.8.4.4', '8.8.8.8:53']
# ...
```

--------------------------------

### Pattern Matching Rules

Source: https://stash.wiki/en/rules/rule-types

Documentation for matching traffic based on User-Agent headers or URL regular expressions.

```APIDOC
## USER-AGENT
Matches requests via the User-Agent header.
Example: `USER-AGENT,AppleNews*,PROXY`

## URL-REGEX
Matches links using regular expressions.
Example: `URL-REGEX,^https?:\/\/www\.amazon\.com\/(Amazon-Video|gp\/video)\/,PROXY`
```

--------------------------------

### HTTP Proxy Configuration

Source: https://stash.wiki/en/proxy-protocols/proxy-types

Configuration for an HTTP proxy, with options for TLS (HTTPS), certificate verification, username, and password.

```yaml
name: http
type: http
server: server
port: 443
headers:
  key: value
tls: true # https
skip-cert-verify: true
# username: username
# password: password
```

--------------------------------

### Import Remote Override

Source: https://stash.wiki/en/faq/url-schema

Instructions for importing remote override files using different URL schemas. The URL must be URL-encoded when using `stash://` or `clash://`.

```APIDOC
## Import Remote Override

### Description
Import a remote override file into Stash.

### Methods
- `stash://install-override?url=${url-encoded}`
- `clash://install-override?url=${url-encoded}`
- `https://link.stash.ws/install-override/example.com/stash.stoverride`

### Notes
- For `stash://` and `clash://`, the `url` parameter must be URL-encoded.
- For `https://link.stash.ws`, the URL format is `https://link.stash.ws/install-override/<remote-url>`, where `<remote-url>` is the URL to the override file (e.g., `example.com/stash.stoverride`). This URL does not need to be encoded and does not include the schema.
```

--------------------------------

### Match URL-REGEX

Source: https://stash.wiki/en/rules/rule-types

Syntax for matching URLs using regular expressions.

```text
URL-REGEX,^https?:\/\/www\.amazon\.com\/(Amazon-Video|gp\/video)\/,PROXY
```

--------------------------------

### Logical Rules (AND, OR, NOT)

Source: https://stash.wiki/en/rules/rule-types

Documentation for combining multiple rules using logical operators.

```APIDOC
## Logical Rules

### AND
`AND,((#Rule1), (#Rule2), ...),PROXY`
Matches if all sub-rules are satisfied. Supports `no-resolve` parameter.

### OR
`OR,((#Rule1), (#Rule2), ...),PROXY`
Matches if at least one sub-rule is satisfied.

### NOT
`NOT,((#Rule1)),PROXY`
Negates the result of the provided rule.
```

--------------------------------

### SOCKS5 Configuration

Source: https://stash.wiki/en/proxy-protocols/proxy-types

Configuration for a SOCKS5 proxy. Optional parameters for username, password, TLS, and UDP are commented out.

```yaml
name: socks
type: socks5
server: server
port: 443
# username: username
# password: password
# tls: true
# skip-cert-verify: true
# udp: true
```

--------------------------------

### Configure Direct Proxy with Interface

Source: https://stash.wiki/en/proxy-protocols/proxy-types

Forces traffic through a specific network interface using a direct proxy type.

```yaml
name: my-corp-vpn
type: direct
interface-name: utun3
```

```yaml
rules:
  - IP-CIDR,10.4.8.0/24,my-corp-vpn
```

--------------------------------

### Proxy Set Structure

Source: https://stash.wiki/en/proxy-protocols/proxy-providers

A valid remote proxy set configuration must include the `proxies` field, listing individual proxy configurations.

```yaml
proxies:
  - name: 'ss1'
    type: ss
    server: server
    port: 443
    cipher: AEAD_CHACHA20_POLY1305
    password: 'password'
  - name: 'ss2'
    type: ss
    server: server
    port: 443
    cipher: AEAD_CHACHA20_POLY1305
    password: 'password'
```

--------------------------------

### Configure Script Provider with URL

Source: https://stash.wiki/en/script/manage-script

Use this to download and cache scripts from a remote URL with a specified interval. Stash respects Etag and Last-Modified headers for efficient updates.

```yaml
script-providers:
  your-fancy-script:
    url: https://your-fancy-script.com/your-fancy-script.js
    interval: 86400
```

--------------------------------

### Obfs Plugin Configuration for Shadowsocks

Source: https://stash.wiki/en/proxy-protocols/proxy-types

Configure the obfs plugin for Shadowsocks to obfuscate TCP traffic. Requires specifying the obfuscation mode and host.

```yaml
plugin: obfs
plugin-opts:
  mode: tls # Obfuscation mode, can choose between http or tls
  host: bing.com # Obfuscation domain, must match the server configuration
```

--------------------------------

### Configure HTTP URL and Header Rewriting

Source: https://stash.wiki/en/http-engine/rewrite

Defines rules for URL redirection, header manipulation, and basic mock responses using regular expressions.

```yaml
http:
  # HTTP(S) rewrite supporting various strategies such as header, 302, 307, reject
  url-rewrite:
    - ^http://g\.cn https://www.google.com transparent
    - ^https?://www\.google\.cn https://www.google.com 302 # Directly returns a 302 redirect response
    - ^https?://ad\.example - reject # Rejects the request
  header-rewrite:
    - ^http://g\.cn request-add DNT 1
    - ^http://g\.cn request-del DNT
    - ^http://g\.cn request-replace DNT 1
    - ^http://g\.cn request-replace-regex User-Agent Go-http-client curl
 
    - ^http://g\.cn response-add DNT 1
    - ^http://g\.cn response-del DNT
    - ^http://g\.cn response-replace DNT 1
    - ^http://g\.cn response-replace-regex User-Agent Go-http-client curl
  mock:
    - match: ^https?://ad\.example
      status-code: 503
```

--------------------------------

### Shadowsocks (ss) Proxy Configuration

Source: https://stash.wiki/en/proxy-protocols/proxy-types

Basic configuration for a Shadowsocks proxy, including server, port, cipher, password, and UDP support.

```yaml
name: ss1
type: ss
server: server
port: 443
cipher: chacha20-ietf-poly1305
password: 'password'
udp: true
plugin: null
plugin-opts:
  mode:
  host:
```

--------------------------------

### Snell Configuration

Source: https://stash.wiki/en/proxy-protocols/proxy-types

Configuration for Snell, a modern proxy protocol. UDP support requires v3 and above server. Obfuscation modes are available.

```yaml
name: snell
type: snell
server: server
port: 443
psk: yourpsk
udp: true # Requires v3 and above server
version: 3
# obfs-opts:
# mode: http # or tls
# host: bing.com
```

--------------------------------

### Manage Script with URL, Path, and Payload

Source: https://stash.wiki/en/script/manage-script

Specify a local `path` for cache management alongside `url` and `payload`. Stash uses the local file if it exists, otherwise uses the payload, and updates from the URL. Path traversal is limited.

```yaml
script-providers:
  your-fancy-script:
    url: https://your-fancy-script.com/your-fancy-script.js
    path: ./fancy/script.js
    interval: 86400
    payload: |
      console.log("This is a test script");
      $done();
```

--------------------------------

### Select Strategy Group Configuration

Source: https://stash.wiki/en/proxy-protocols/proxy-groups

The select strategy allows users to manually choose a proxy from a list. It can also be used for automatic switching based on network conditions.

```yaml
- name: select
  type: select
  proxies:
    - ss1
    - ss2
    - vmess
    - auto
```

--------------------------------

### Hysteria Configuration

Source: https://stash.wiki/en/proxy-protocols/proxy-types

Configuration for Hysteria, optimized for harsh network environments using a modified QUIC protocol. Bandwidth should be specified in Mbps.

```yaml
name: 'hysteria'
type: hysteria
server: server
port: 443
up-speed: 100 # Upload bandwidth in Mbps
down-speed: 100 # Download bandwidth in Mbps
auth-str: your-password
# auth: aHR0cHM6Ly9oeXN0ZXJpYS5uZXR3b3JrL2RvY3MvYWR2YW5jZWQtdXNhZ2Uv # bytes encoded in base64
protocol: '' # udp / wechat-video
obfs: '' # obfs password
sni: example.com # Server Name Indication, uses server value if empty
alpn:
  - hysteria
skip-cert-verify: true
```

--------------------------------

### Advanced HTTP POST Request with Options

Source: https://stash.wiki/en/script/syntax-and-interface

Perform an HTTP POST request with custom headers, proxy, body, and other options. Handles potential errors and logs the response data.

```javascript
const yourProxyName = 'a fancy name with 😄'

$httpClient.post(
  {
    url: 'http://httpbin.org/post',
    headers: {
      'X-Header-Key': 'headerValue',
      'X-Stash-Selected-Proxy': encodeURIComponent(yourProxyName),
    },
    body: '{}', // can be object or string
    timeout: 5,
    insecure: false,
    'binary-mode': true,
    'auto-cookie': true,
    'auto-redirect': true,
  },
  (error, response, data) => {
    if (error) {
      console.log(error)
    } else {
      console.log(data)
    }
  }
)
```

--------------------------------

### Define Remote Proxy Sets

Source: https://stash.wiki/en/proxy-protocols/proxy-providers

Configure remote proxy sets under `proxy-providers` to enable automatic background updates. Reference these providers in `proxy-groups` using the `use` field. Ensure the remote proxy set contains a `proxies` field.

```yaml
proxy-providers:
  provider-a:
    url: https://raw.githubusercontent.com/STASH-NETWORKS-LIMITED/stash-example/main/config.yaml
    interval: 3600
    filter: 'example'
 
  provider-b:
    url: https://raw.githubusercontent.com/STASH-NETWORKS-LIMITED/stash-example/main/config.yaml
    interval: 3600
 
proxy-groups:
  - name: auto
    type: url-test
    interval: 300
    use:
      - provider-a # reference to provider-a
      - provider-b # reference to provider-b
```

--------------------------------

### Configure Hostname Mapping in Stash

Source: https://stash.wiki/en/features/hosts

Define local DNS overrides using the hosts block and proxy-specific overrides using the proxy-hosts block.

```yaml
hosts:
  +.stash.dev: 127.0.0.1
  one.one.one.one: [1.0.0.1, 1.1.1.1]
  manual.stash.ws: stash.wiki
 
proxy-hosts:
  api.twitter.com: 2606:4700:4700::1001
```

--------------------------------

### Disable QUIC Protocol via Script Shortcut

Source: https://stash.wiki/en/faq/effective-stash

Use this script configuration to reject UDP traffic on port 443, effectively disabling the QUIC protocol.

```yaml
script:
  shortcuts:
    quic: network == 'udp' and dst_port == 443
 
rules:
  - SCRIPT,quic,REJECT
```

--------------------------------

### HTTP Client

Source: https://stash.wiki/en/script/syntax-and-interface

Provides methods for making HTTP requests.

```APIDOC
## HTTP Client

### Description
Make HTTP requests to specified URLs.

### Methods
- `$httpClient.get(url<String>, callback<Function>)`
- `$httpClient.get(request<Object>, callback<Function>)`
- `$httpClient.post(request<Object>, callback<Function>)`
- `$httpClient.put(request<Object>, callback<Function>)`
- `$httpClient.delete(request<Object>, callback<Function>)`
- `$httpClient.head(request<Object>, callback<Function>)`
- `$httpClient.options(request<Object>, callback<Function>)`
- `$httpClient.patch(request<Object>, callback<Function>)`

### Request Options
When using the object-based request format, the following options are available:
- `url` (String): The URL to request.
- `headers` (Object): An object containing request headers. Special headers like `X-Stash-Selected-Proxy` and `binary-mode` can be set here.
- `body` (String | Object): The request body. Can be a string or a JSON object.
- `timeout` (Number): The request timeout in seconds (default is 5 seconds).
- `insecure` (Boolean): Set to `true` to ignore SSL certificate validation.
- `'binary-mode'` (Boolean): Set to `true` to enable binary mode for the response.
- `'auto-cookie'` (Boolean): Set to `true` to automatically handle cookies.
- `'auto-redirect'` (Boolean): Set to `true` to automatically follow redirects.

### Callback Function
The callback function for HTTP requests receives three arguments:
- `error`: An error object if the request failed, otherwise `null`.
- `response`: An object containing the response details (e.g., status code, headers).
- `data`: The response data (body).

### Request Example (GET)
```javascript
$httpClient.get('http://httpbin.org/get', (error, response, data) => {
  if (error) {
    console.log(error)
  } else {
    console.log(data)
  }
})
```

### Request Example (POST with options)
```javascript
const yourProxyName = 'a fancy name with 😄'

$httpClient.post(
  {
    url: 'http://httpbin.org/post',
    headers: {
      'X-Header-Key': 'headerValue',
      'X-Stash-Selected-Proxy': encodeURIComponent(yourProxyName),
    },
    body: '{}', // can be object or string
    timeout: 5,
    insecure: false,
    'binary-mode': true,
    'auto-cookie': true,
    'auto-redirect': true,
  },
  (error, response, data) => {
    if (error) {
      console.log(error)
    } else {
      console.log(data)
    }
  }
)
```
```

--------------------------------

### USER-AGENT Rule

Source: https://stash.wiki/en/en/rules/rule-types

Matches requests based on the User-Agent header. Supports wildcard matching.

```APIDOC
## USER-AGENT

Matches via User-Agent request header.
`USER-AGENT,AppleNews*,PROXY`
```

--------------------------------

### Define MitM Domain List in YAML

Source: https://stash.wiki/en/http-engine/mitm

Specify domain names and wildcards to enable MitM interception for specific hosts.

```yaml
http:
  # List of domain names to enable MitM for, ensuring that the above CA certificate is trusted by the system
  mitm:
    - g.cn
    - '*.google.cn'
    - weather-data.apple.com # Only enabled for port 443 by default
    - weather-data.apple.com:* # Enable for all ports using wildcard
    - '*.weather-data.apple.com' # Wildcards can also be used in domain names
```

--------------------------------

### $done() Function

Source: https://stash.wiki/en/script/rewrite-requests

Explains the usage of the `$done()` function, which is mandatory for releasing resources and can be used to modify requests or responses.

```APIDOC
## `$done(value)`

⚠️ For all scripts, you must call the `$done(value)` method to release resources at the end.

For scripts of the request type, calling `$done(object)` can rewrite the HTTP request, `object` can include the following fields:

* `url`: Modify the request URL
* `headers`: Modify the request headers
* `body`: Modify the request body
* `response`: Replace the HTTP response, no longer actually send the HTTP request

You can call `$done()` to interrupt the request, or `$done({})` to not modify any content of the request.

For scripts of the response type, calling `$done(object)` can rewrite the HTTP response, `object` can include the following fields:

* `status`: Modify the response status code
* `headers`: Modify the response headers
* `body`: Modify the response body

You can call `$done()` to interrupt the request, or `$done({})` to not modify any content of the response.
```

--------------------------------

### HTTP Rewrite Script Configuration

Source: https://stash.wiki/en/script/rewrite-requests

This section details the configuration format for enabling HTTP rewrite scripts in Stash, including matching rules, script provider settings, and available parameters.

```APIDOC
## HTTP Rewrite Script Configuration

Users can modify the HTTP requests and responses flowing through Stash via JavaScript scripts.

### Configuration Format
```yaml
http:
  script:
    - match: url-you-want-to-match
      name: your-fancy-script
      type: response # request / response
      require-body: true
      timeout: 20
      argument: ''
      binary-mode: false
      max-size: 1048576 # 1MB

script-providers:
  your-fancy-script:
    url: https://your-fancy-script.com/your-fancy-script.js
    interval: 86400
```

### Parameters

* `match`: The URL regular expression that the script matches.
* `type`: The type of script, optional values are `request` or `response`.
* `require-body`: Whether the request body / response body is needed. Processing the body in the script requires more memory space; enable only when necessary.
* `timeout`: The script execution timeout, in seconds.
* `argument`: The argument when the script is executed, type is `string`.
* `binary-mode`: Binary mode, `body` will be passed to the script as `Uint8Array` instead of `string`.
* `max-size`: In bytes, requests with a body size exceeding this will not trigger the script.

💡 Binary mode is only supported in Stash iOS 2.0.2 and later versions.
```

--------------------------------

### URL Encoding and Scheme

Source: https://stash.wiki/en/faq/url-schema

Information regarding URL encoding requirements and default remote URL schema.

```APIDOC
## URL Encoding and Scheme

### URL Encoding
URLs used with `stash://` and `clash://` schemas **need to be encoded.**

### `link.stash.ws` Usage
URLs used with `https://link.stash.ws` **do not contain Schema and do not need to be encoded.** The format is `https://link.stash.ws/command/url`.

### Default Remote URL Schema
The default remote URL schema is HTTPS. To use HTTP, add the parameter `?scheme=http`.

### Error Handling
If the remote URL cannot be accessed, the link will return `404`.
```

--------------------------------

### Url-Test Strategy Group Configuration

Source: https://stash.wiki/en/proxy-protocols/proxy-groups

Use url-test to periodically check proxy connectivity, select the fastest server, and skip unhealthy ones. Set the interval for latency tests in seconds.

```yaml
- name: auto
  type: url-test
  proxies:
    - ss1
    - ss2
    - vmess
  interval: 300
```

--------------------------------

### Configure Tailscale Proxy

Source: https://stash.wiki/en/proxy-protocols/proxy-types

Configuration templates for Tailscale nodes and routing rules. Ensure Key Expiry is disabled in the Tailscale admin console.

```yaml
name: tailnet-main
type: tailscale
auth-key: tskey-auth-xxxxxxxxxxxxxxxx
hostname: tailnet-main
control-url: https://controlplane.tailscale.com
ephemeral: false
exit-node: exit-gateway.tailnet-main.ts.net
```

```yaml
proxies:
  - name: tailnet-main
    type: tailscale
    auth-key: tskey-auth-xxxxxxxxxxxxxxxx
 
rules:
  - DOMAIN,app.tailnet-main.ts.net,tailnet-main
  - IP-CIDR,100.64.0.0/10,tailnet-main,no-resolve
```

--------------------------------

### Configure DNS Servers in Stash

Source: https://stash.wiki/en/features/dns-server

Defines the default nameservers and primary DNS service providers. Only IP addresses are supported for default-nameserver entries.

```yaml
dns:
  # The DNS servers listed below will be used to resolve domain names for DNS services
  # Only fill in the IP addresses of DNS servers
  default-nameserver:
    - 223.5.5.5
    - 114.114.114.114
  # DNS services supporting UDP / TCP / DoT / DoH / DoQ protocols, with specific connection port numbers if needed.
  # All DNS requests will be sent directly to the servers without going through any proxies.
  # Stash will reply to DNS requests with the first obtained resolution record
  nameserver:
    # It is not recommended to configure more than 2 DNS servers as it may increase system power consumption
    - https://doh.pub/dns-query
    - https://dns.alidns.com/dns-query
    - quic://dns.adguard.com:853
    - doq://test.dns.nextdns.io:853
    - system # Use iOS system DNS
 
  # Skip certificate verification to resolve some compatibility issues https://help.nextdns.io/t/g9hdkjz
  skip-cert-verify: true
 
  # DNS queries follow proxy rules
  follow-rule: false
```