How to Configure CFnew Using Cloudflare KV for Dynamic Management

CFnew stores its runtime configuration in Cloudflare KV, enabling instant, code-free updates directly from the web UI without requiring new deployments.

CFnew is an open-source proxy solution built on Cloudflare Workers that supports VLESS and Trojan protocols. When you configure CFnew using Cloudflare KV for dynamic management, all runtime settings—including protocol toggles, proxy IPs, and API endpoints—live in a KV namespace, allowing real-time modifications through a graphical interface or API calls.

Setting Up the KV Namespace

Creating and Binding the Namespace

To enable dynamic configuration, you must create a KV namespace and bind it to your Worker with the specific binding name C.

1. Navigate to the Cloudflare dashboard and select Workers & Pages → KV → Create namespace.
2. In your Worker settings, go to Settings → KV Namespaces → Add binding.
3. Set the Binding name to exactly C (this hardcoded identifier is required by the CFnew source code).
4. Select the namespace you created in step 1.

According to the README.md in the byJoey/cfnew repository, this binding is the only infrastructure requirement beyond the Worker itself.

Configuring the Worker

Minimal wrangler.toml Configuration

CFnew requires only a single line in wrangler.toml to establish compatibility. The KV binding is managed through the Cloudflare UI, not the configuration file.

# wrangler.toml

compatibility_date = "2026-01-20"

# KV binding is configured in Cloudflare UI:

#   Binding name: C

#   Namespace: <your-kv-namespace>

As shown in the repository's wrangler.toml, no additional keys or environment variables are necessary for basic operation. The CI workflow in .github/workflows/test.yml verifies that the Worker compiles correctly against this minimal configuration.

Dynamic Configuration via the Web UI

Accessing the Management Interface

Once deployed, access the configuration panel at your Worker's URL:

https://<your-worker>.workers.dev/<UUID-or-custom-path>

This same endpoint serves both subscription requests and the management interface. The UI renders dynamically by reading the current KV state on each request.

Real-Time Configuration Updates

All configuration items are stored as JSON strings under specific keys in the KV namespace. When you modify settings through the web UI—such as enabling VLESS, setting preferred IPs, or toggling the API flag—the interface writes directly to KV via the Cloudflare API. The Worker reads these values on every incoming request, applying changes immediately without a redeployment.

Common configuration keys include:

• ev – Controls VLESS protocol enablement ("yes" or "no")
• et – Controls Trojan protocol enablement
• yxby – Additional feature toggles
• preferred-ips – Array of custom endpoint configurations

Programmatic KV Access

Reading Configuration in the Worker

The Worker accesses configuration through the env.C binding. In the fetch handler, retrieve and parse the configuration object as follows:

export default {
  async fetch(request, env) {
    // env.C is the KV binding named "C"
    const raw = await env.C.get('config');
    const cfg = raw ? JSON.parse(raw) : {};

    // Example: enable VLESS only if cfg.ev !== 'no'
    const enableVless = cfg.ev !== 'no';
    
    // Proceed with protocol handling...
    return new Response('OK');
  }
}

This pattern allows the Worker to evaluate feature flags and routing logic dynamically on every request.

Updating Settings via API

You can programmatically modify configuration by posting to the CFnew API endpoint, which internally writes to the KV store:

curl -X POST "https://your-worker.workers.dev/<UUID>/api/preferred-ips" \
  -H "Content-Type: application/json" \
  -d '{"ip":"1.2.3.4","port":443,"name":"HongKong Node"}'

This approach is identical to the operations performed by the graphical UI.

Manual KV Management with Wrangler

For automation or bulk updates, use the Wrangler CLI to write configuration directly:

# Write a complete configuration object

wrangler kv:key put config '{"ev":"yes","et":"no","yxby":"no"}' --binding C

# Update specific individual keys

wrangler kv:key put preferred-ips '[{"ip":"1.2.3.4","port":443}]' --binding C

Summary

• Create a KV namespace in the Cloudflare dashboard and bind it to your Worker with the exact name C.
• Deploy CFnew using a minimal wrangler.toml containing only compatibility_date.
• Access the UI at your Worker's domain to manage configuration through a web interface.
• Modify settings instantly—changes written to KV take effect immediately without redeployment.
• Automate configuration using the built-in API endpoints or Wrangler CLI commands.

Frequently Asked Questions

What is the required KV binding name for CFnew?

The binding must be named exactly C (uppercase). This identifier is hardcoded in the CFnew source code; using any other binding name will prevent the Worker from accessing its configuration store.

How do I access the CFnew configuration UI?

Visit https://<your-worker>.workers.dev/<UUID-or-custom-path> after deployment. This URL serves both your subscription links and the management interface, which reads the current KV state to populate the configuration forms.

Can I update CFnew settings without redeploying the Worker?

Yes. Because configuration is stored in Cloudflare KV rather than environment variables or code, any changes made through the web UI, API, or Wrangler CLI are immediately available to the Worker on its next request execution.

What configuration options can be managed through KV?

You can manage protocol toggles (VLESS/Trojan), preferred IP lists, API enable flags, and custom routing rules. All values are stored as JSON strings under keys like config and preferred-ips, which the Worker parses at runtime to determine behavior.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}