3. Install, Start, and Verify#

This chapter focuses only on the user perspective: how to prepare a configuration, import and apply it in the Link1 App, verify the configuration when running the core directly, and confirm that the proxy is working.

Recommended Method: Manage with the Link1 App#

Regular users are advised to complete the following workflow through the Link1 App:

1. Create a new configuration profile.

1. Paste YAML, import a local file, or enter a subscription URL.

1. Click validate to confirm there are no field errors or reference errors.

1. Apply the configuration and wait for the core to finish starting.

1. On the App home page, confirm the running status, current mode, real-time speed, and log summary.

1. Enable system proxy, TUN, or router mode so traffic enters Link1.

1. Use the connection list, policy groups, and logs to confirm traffic is forwarded as expected.

The App automatically handles the internal management channel, status synchronization, and page display. Users usually do not need to write additional management configuration manually.

Configuration File Location#

The default configuration file name is config.yaml. If you run the core directly, you can specify it with -f:

spark -f /path/to/config.yaml

Specify the working directory with -d:

spark -d /path/to/workdir -f /path/to/config.yaml

Practical effects:

• Relative paths are resolved based on the configuration file directory or the working directory.

• provider caches, state databases, Fake-IP persistence, and downloaded subscription files are usually related to the working directory.

• For router deployments, it is recommended to use a fixed working directory to avoid relative path changes after reboot.

• If you use the App, the working directory is generally managed by the App. You only need to focus on the configuration profile itself.

Common Command-Line Arguments for Users#

These arguments are mainly used for troubleshooting, router deployments, or development debugging. Desktop users should prioritize the configuration import and validation buttons in the Link1 App.

Step 1: Write a Minimal Configuration#

mixed-port: 7890
mode: rule
log-level: info
allow-lan: false

proxies:
  - name: example-socks
    type: socks5
    server: 127.0.0.1
    port: 1080
    udp: true

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - example-socks
      - DIRECT

rules:
  - MATCH,PROXY

If you do not have an upstream proxy yet, you can also use direct connection only to verify that the core can start:

mixed-port: 7890
mode: rule
log-level: info
rules:
  - MATCH,DIRECT

Step 2: Verify the Configuration#

In the App, click “Validate Configuration”. If running the core directly:

spark -f config.yaml -t

If the configuration is invalid, Link1 will try to tell you the path, for example:

compile config "config.yaml": proxies[0].server is empty

How to read it:

• proxies[0]: the first node in the proxies list.

• .server is empty: this node is missing server.

Common errors and meanings:

Step 3: Start Link1#

In the App, click start or apply the configuration. When running the core directly:

spark -d . -f config.yaml

A successful startup does not mean the proxy is already usable. You still need to confirm that traffic is actually entering Link1.

Step 4: Connect Clients to Link1#

Browser or System Proxy#

Enter:

HTTP proxy: 127.0.0.1:7890
HTTPS proxy: 127.0.0.1:7890
SOCKS5 proxy: 127.0.0.1:7890

mixed-port accepts both HTTP proxy and SOCKS5. For first-time use, it is recommended to set only the browser proxy to avoid a system-wide proxy affecting other applications.

Verify with curl#

curl -x http://127.0.0.1:7890 https://www.example.com/

To verify Cloudflare WARP:

curl -x http://127.0.0.1:7890 https://www.cloudflare.com/cdn-cgi/trace

Do not combine --noproxy '*' with -x; --noproxy '*' bypasses the proxy.

Verify in the App#

After the request is sent, confirm in the Link1 App:

• The target domain or target IP appears in the connection list.

• The matched rule is visible in the connection details.

• The outbound shows the node or policy group you expect.

• The logs do not show continuous DNS, authentication, handshake, or timeout errors.

If curl succeeds but the App connection list does not change, it usually means the request did not go through Link1, or you are not viewing the currently running configuration profile.

LAN Usage#

If you want other devices on the same LAN to use Link1:

mixed-port: 7890
allow-lan: true
bind-address: '*'
lan-allowed-ips:
  - 192.168.0.0/16
authentication:
  - alice:password

Practical effects:

• Link1 listens on all network interfaces.

• LAN devices can set the proxy to the Link1 host IP, for example 192.168.9.2:7890.

• lan-allowed-ips restricts which source IPs are allowed to access it.

• authentication requires clients to enter a username and password.

Risk: Do not expose the proxy port without authentication on public Wi-Fi or untrusted networks.

Router Usage#

Common approaches on routers:

• Explicit proxy: devices manually enter the router IP and mixed-port.

• Transparent proxy: use redir-port, tproxy-port, or tun to take over device traffic.

• DNS takeover: point LAN device DNS to the router, then let Link1 DNS handle it.

If you use TUN:

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16

tun:
  enable: true
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

The key in router scenarios is not whether the core has started, but three things:

1. Whether LAN device traffic is taken over by the router.

1. Whether DNS from LAN devices enters Link1.

1. Whether Link1 outbound traffic can access the internet from the router itself.

Common Startup Issues#