# How to Add Custom Proxy Chains Using the Enhancement System in Clash Nyanpasu

> Learn to add custom proxy chains in Clash Nyanpasu using its enhancement system. Developers can define proxy groups and routing rules with JavaScript or Lua. Enable the built-in engine and utilize chain.add() for flexible confi...

- Repository: [Nyanpasu/clash-nyanpasu](https://github.com/libnyanpasu/clash-nyanpasu)
- Tags: how-to-guide
- Published: 2026-03-06

---

**Developers can add custom proxy chains in Clash Nyanpasu by enabling the built-in enhancement engine (`enable_builtin_enhanced: true`) in a profile and providing a JavaScript or Lua script that uses the `chain.add()` API to programmatically define proxy groups and routing rules.**

The **enhancement system** in [Clash Nyanpasu](https://github.com/libnyanpasu/clash-nyanpasu) allows developers to extend profile functionality without modifying the core application. By leveraging embedded JavaScript or Lua scripts, you can dynamically inject **custom proxy chains**—complex routing sequences that direct traffic through multiple proxy hops—directly into the generated Clash configuration.

## Understanding the Enhancement System Architecture

The enhancement system operates as a preprocessing layer between the raw profile and the Clash core. When a profile with enhancements enabled is loaded, the backend executes the specified script in a sandboxed QuickJS or Lua VM, then merges the script's output into the final configuration.

Key architectural components include:

- **Backend entry point**: [`backend/tauri/src/enhance/mod.rs`](https://github.com/libnyanpasu/clash-nyanpasu/blob/main/backend/tauri/src/enhance/mod.rs) contains the `enhance()` function that orchestrates script execution and configuration merging.
- **Chain API**: [`backend/tauri/src/enhance/chain.rs`](https://github.com/libnyanpasu/clash-nyanpasu/blob/main/backend/tauri/src/enhance/chain.rs) implements the `Chain` struct with methods like `add()` and `addRule()` that scripts invoke to manipulate proxy definitions.
- **Script runners**: [`backend/tauri/src/enhance/script/js.rs`](https://github.com/libnyanpasu/clash-nyanpasu/blob/main/backend/tauri/src/enhance/script/js.rs) (QuickJS) and [`backend/tauri/src/enhance/script/lua/mod.rs`](https://github.com/libnyanpasu/clash-nyanpasu/blob/main/backend/tauri/src/enhance/script/lua/mod.rs) (Lua) provide the sandboxed execution environments.
- **Frontend integration**: The UI toggle and IPC bindings in [`frontend/interface/src/service/types.ts`](https://github.com/libnyanpasu/clash-nyanpasu/blob/main/frontend/interface/src/service/types.ts) and [`frontend/interface/src/ipc/bindings.ts`](https://github.com/libnyanpasu/clash-nyanpasu/blob/main/frontend/interface/src/ipc/bindings.ts) allow users to enable enhancements and trigger re-processing.

## Enabling Custom Proxy Chains in Your Profile

To activate the enhancement engine for **custom proxy chains**, you must set `enable_builtin_enhanced: true` in your profile YAML and specify the path to your enhancement script.

```yaml

# example-profile.yaml

name: Custom-Chain-Profile
port: 7890
socks-port: 7891
allow-lan: false
mode: rule
log-level: info

# Enable the enhancement engine

enable_builtin_enhanced: true

# Path to the script (relative to the profile directory)

script: my-chain.js

```

When this profile is selected in the Clash Nyanpasu UI, the backend automatically loads [`my-chain.js`](https://github.com/libnyanpasu/clash-nyanpasu/blob/main/my-chain.js) and executes it against the configuration context.

## Writing Enhancement Scripts for Proxy Chains

Enhancement scripts interact with a context object exposing the `chain` and `dns` APIs. You can write these scripts in either **JavaScript** or **Lua**, depending on your preference.

### JavaScript Implementation

The JavaScript runner uses QuickJS. The global `chain` object provides methods to construct proxy groups and routing rules.

```javascript
// my-chain.js - Custom proxy chain definition
// Run by the built-in QuickJS runner in backend/tauri/src/enhance/script/js.rs

// 1. Create a "select" proxy group containing three regional proxies
chain.add('My-Proxy-Chain', 'select', [
  '🇺🇸 US-Proxy',
  '🇯🇵 JP-Proxy',
  '🇭🇰 HK-Proxy',
]);

// 2. Add a rule routing all example.com traffic through the custom chain
chain.addRule('DOMAIN-SUFFIX,example.com,My-Proxy-Chain');

// 3. (Optional) Inject a DNS-over-TLS server for this chain
dns.addServer('tls://1.1.1.1');

```

### Lua Implementation

The Lua implementation offers identical functionality through the same API surface, processed by [`backend/tauri/src/enhance/script/lua/mod.rs`](https://github.com/libnyanpasu/clash-nyanpasu/blob/main/backend/tauri/src/enhance/script/lua/mod.rs).

```lua
-- my-chain.lua - Equivalent Lua implementation
-- Processed by backend/tauri/src/enhance/script/lua/mod.rs

-- Build the proxy group
chain.add('Fast-Chain', 'select', {
  '🇺🇸 US-Fast',
  '🇬🇧 UK-Fast',
  '🇸🇬 SG-Fast',
})

-- Route Google domains through the chain
chain.addRule('DOMAIN-KEYWORD,google,Fast-Chain')

-- Add DNS server (optional)
dns.addServer('tls://1.0.0.1')

```

## Key API Methods for Proxy Chain Manipulation

The enhancement context exposes three primary APIs for **custom proxy chains**:

- **`chain.add(name, type, selectors, options?)`** – Creates a new proxy group. The `type` parameter accepts standard Clash group types (`select`, `url-test`, `fallback`, `load-balance`). The `selectors` array lists proxy names or other groups to include.
- **`chain.addRule(rule)`** – Appends a rule string to the global rule list. Rules follow standard Clash syntax (`DOMAIN-SUFFIX`, `DOMAIN-KEYWORD`, `IP-CIDR`, etc.) and must reference valid proxy groups created via `chain.add()`.
- **`dns.addServer(url)`** – Injects a DNS server configuration. Accepts standard DNS URLs including DoT (`tls://`) and DoH (`https://`) formats.

These methods are implemented in [`backend/tauri/src/enhance/chain.rs`](https://github.com/libnyanpasu/clash-nyanpasu/blob/main/backend/tauri/src/enhance/chain.rs) and exposed to the script runtimes through the respective binding layers.

## Backend Implementation Details

The enhancement system processes **custom proxy chains** through a specific execution pipeline:

1. **Configuration Loading**: When a profile is selected, [`backend/tauri/src/config/nyanpasu/mod.rs`](https://github.com/libnyanpasu/clash-nyanpasu/blob/main/backend/tauri/src/config/nyanpasu/mod.rs) checks for `enable_builtin_enhanced: true`.
2. **Script Execution**: The `enhance()` function in [`backend/tauri/src/enhance/mod.rs`](https://github.com/libnyanpasu/clash-nyanpasu/blob/main/backend/tauri/src/enhance/mod.rs) loads the script file specified in the `script:` field.
3. **Runtime Binding**: Depending on file extension, either [`backend/tauri/src/enhance/script/js.rs`](https://github.com/libnyanpasu/clash-nyanpasu/blob/main/backend/tauri/src/enhance/script/js.rs) (QuickJS) or [`backend/tauri/src/enhance/script/lua/mod.rs`](https://github.com/libnyanpasu/clash-nyanpasu/blob/main/backend/tauri/src/enhance/script/lua/mod.rs) (Lua) initializes the VM and binds the `chain` and `dns` APIs.
4. **Object Merging**: The script's output is collected into intermediate structures defined in [`backend/tauri/src/enhance/chain.rs`](https://github.com/libnyanpasu/clash-nyanpasu/blob/main/backend/tauri/src/enhance/chain.rs), then merged with the base profile using utilities in [`backend/tauri/src/enhance/utils.rs`](https://github.com/libnyanpasu/clash-nyanpasu/blob/main/backend/tauri/src/enhance/utils.rs).
5. **Core Handoff**: The final merged configuration is written to disk and loaded by the Clash core.

This architecture ensures that **custom proxy chains** are computed dynamically while maintaining sandboxed execution of user scripts.

## Frontend Integration

Users interact with the enhancement system through the React-based frontend:

- **Type Definitions**: The `EnableBuiltinEnhanced` boolean type is defined in [`frontend/interface/src/service/types.ts`](https://github.com/libnyanpasu/clash-nyanpasu/blob/main/frontend/interface/src/service/types.ts).
- **IPC Bindings**: The `enhanceProfiles()` function in [`frontend/interface/src/ipc/bindings.ts`](https://github.com/libnyanpasu/clash-nyanpasu/blob/main/frontend/interface/src/ipc/bindings.ts) provides the channel to trigger re-enhancement after script edits.
- **UI Component**: The toggle checkbox is implemented in [`frontend/interface/src/components/setting/setting-nyanpasu-misc.tsx`](https://github.com/libnyanpasu/clash-nyanpasu/blob/main/frontend/interface/src/components/setting/setting-nyanpasu-misc.tsx), labeled "Enable Built-in Enhanced".

When a user toggles this setting or edits a script, the frontend calls `enhanceProfiles()` to force the backend to re-run the enhancement pipeline and update the active **custom proxy chains**.

## Summary

Developers can implement **custom proxy chains** in Clash Nyanpasu by leveraging the built-in enhancement engine:

- Enable enhancements by setting `enable_builtin_enhanced: true` in the profile YAML and specifying a `script:` path.
- Write JavaScript or Lua scripts that use the `chain.add()`, `chain.addRule()`, and `dns.addServer()` APIs to define proxy groups and routing logic.
- The backend processes these scripts in [`backend/tauri/src/enhance/mod.rs`](https://github.com/libnyanpasu/clash-nyanpasu/blob/main/backend/tauri/src/enhance/mod.rs) using sandboxed QuickJS or Lua VMs, merging the output into the final Clash configuration.
- The frontend provides UI controls in [`frontend/interface/src/components/setting/setting-nyanpasu-misc.tsx`](https://github.com/libnyanpasu/clash-nyanpasu/blob/main/frontend/interface/src/components/setting/setting-nyanpasu-misc.tsx) to toggle enhancements and trigger re-processing via `enhanceProfiles()`.

This system allows dynamic, scriptable proxy chain customization without rebuilding the application or modifying core source code.

## Frequently Asked Questions

### What scripting languages are supported for custom proxy chains?

Clash Nyanpasu supports both **JavaScript** and **Lua** for writing enhancement scripts. JavaScript runs inside a QuickJS sandbox ([`backend/tauri/src/enhance/script/js.rs`](https://github.com/libnyanpasu/clash-nyanpasu/blob/main/backend/tauri/src/enhance/script/js.rs)), while Lua uses the embedded Lua interpreter ([`backend/tauri/src/enhance/script/lua/mod.rs`](https://github.com/libnyanpasu/clash-nyanpasu/blob/main/backend/tauri/src/enhance/script/lua/mod.rs)). Both languages expose identical APIs for manipulating proxy chains.

### Where should I place the enhancement script file?

Place the script file in the same directory as your profile YAML file, or provide a relative path in the `script:` field of your profile configuration. The backend resolves the path relative to the profile location when `enable_builtin_enhanced: true` is set and the profile is loaded.

### Can I modify existing proxy groups or only create new ones?

The enhancement API primarily focuses on **creating new** proxy groups via `chain.add()` and adding rules via `chain.addRule()`. While the backend merging logic in [`backend/tauri/src/enhance/utils.rs`](https://github.com/libnyanpasu/clash-nyanpasu/blob/main/backend/tauri/src/enhance/utils.rs) handles combining script output with base configuration, the provided API is designed for additive customization rather than mutating existing profile definitions.

### How do I trigger re-enhancement after editing a script?

After modifying your enhancement script, trigger re-processing by calling the `enhanceProfiles()` IPC method available in [`frontend/interface/src/ipc/bindings.ts`](https://github.com/libnyanpasu/clash-nyanpasu/blob/main/frontend/interface/src/ipc/bindings.ts). The frontend React component [`setting-nyanpasu-misc.tsx`](https://github.com/libnyanpasu/clash-nyanpasu/blob/main/setting-nyanpasu-misc.tsx) provides a UI toggle for enabling enhancements, but manual re-enhancement ensures script changes are immediately applied without restarting the application.