https://github.com/goxray/tun
🌐 CLI Xray VPN client
https://github.com/goxray/tun
go iptables tun tun2socks vpn vpn-client xray-core
Last synced: 5 months ago
JSON representation
🌐 CLI Xray VPN client
- Host: GitHub
- URL: https://github.com/goxray/tun
- Owner: goxray
- License: mit
- Created: 2024-12-15T12:40:28.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-12-29T12:28:22.000Z (6 months ago)
- Last Synced: 2026-01-01T12:49:14.171Z (5 months ago)
- Topics: go, iptables, tun, tun2socks, vpn, vpn-client, xray-core
- Language: Go
- Homepage:
- Size: 1.43 MB
- Stars: 54
- Watchers: 2
- Forks: 10
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Go VPN client for XRay
[](https://goreportcard.com/report/github.com/goxray/tun)
[](https://pkg.go.dev/github.com/goxray/tun)
This project brings fully functioning [XRay](https://github.com/XTLS/Xray-core) VPN client implementation in Go.
> For desktop version see https://github.com/goxray/desktop
> [!NOTE]
> The program will not damage your routing rules, default route is intact and only additional rules are added for the lifetime of application's TUN device. There are also additional complementary clean up procedures in place.
#### What is XRay?
Please visit https://xtls.github.io/en for more info.
#### Tested and supported on:
- macOS (tested on Sequoia 15.1.1)
- Linux (tested on Ubuntu 24.10)
> Feel free to test this on your system and let me know in the issues :)
## ✨ Features
- Stupidly easy to use
- Supports all [Xray-core](https://github.com/XTLS/Xray-core) protocols (vless, vmess e.t.c.) using link notation (`vless://` e.t.c.)
- Only soft routing rules are applied, no changes made to default routes
## ⚡️ Installation
The application can be used standalone, as compiled and thrown somewhere in the directory mentioned in PATH.
##### 📦 3rd party Debian package (maintained by [twdragon](https://github.com/twdragon))
The client is available from the PPA repository `ppa:twdragon/xray`, maintained by [twdragon](https://github.com/twdragon). The network privileges in specified automatically by the postinstall script. The package is in sync with this repo's release tags. You can check the pipeline at the [dedicated repository](https://github.com/twdragon/xray-debian-pkg). To install, use:
```bash
sudo add-apt-repository ppa:twdragon/xray
sudo apt update
sudo apt install goxray-cli
```
After the installation, the package might be updated automatically, as is done in Ubuntu. Packages are signed by [twdragon](https://github.com/twdragon) and published on [Launchpad](https://launchpad.net/~twdragon/+archive/ubuntu/xray). Experimental builds are also available in [pipeline repository](https://github.com/twdragon/xray-debian-pkg/actions).
## ⚡️ Usage
> [!IMPORTANT]
> - `sudo` is required
> - On linux set `sudo setcap cap_net_raw,cap_net_admin,cap_net_bind_service+eip goxray_binary_path`
### Standalone application:
Running the VPN on your machine is as simple as running this little command:
```bash
sudo go run .
```
Where `proto_link` is your XRay link (like `vless://example.com...`), you can get this from your VPN provider or get it from your XRay server.
### As library in your own project:
> [!NOTE]
> This project is built upon the `core` package, see details and documentation at https://github.com/goxray/core
Install:
```bash
go get github.com/goxray/tun/pkg/client
```
Example:
```go
logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelError}))
vpn, _ := client.NewClientWithOpts(client.Config{
TLSAllowInsecure: false,
Logger: logger,
})
_ = vpn.Connect(clientLink)
defer vpn.Disconnect(context.Background())
time.Sleep(60 * time.Second)
```
> Please refer to godoc for supported methods and types.
### As a dockerized experience
If you need to use it with Docker - you can look at [this proposed implementation](https://github.com/goxray/tun/pull/8).
## 🛠 Build
The project compiles like a regular Go program:
```bash
go build -o goxray_cli .
```
#### Cross-compilation
```bash
env GOOS=darwin GOARCH=amd64 go build -o goxray_cli_darwin_amd64 .
```
To cross-compile from macOS to Linux arm/amd I use these commands:
```bash
docker run --platform=linux/arm64 -v=${PWD}:/app --workdir=/app arm64v8/golang:1.24 env GOARCH=arm64 go build -o goxray_cli_linux_arm64 .
```
```bash
docker run --platform=linux/amd64 -v=${PWD}:/app --workdir=/app amd64/golang:1.24 env GOARCH=amd64 go build -o goxray_cli_linux_amd64 .
```
## How it works
- Application sets up new TUN device.
- Adds additional routes to route all system traffic to this newly created TUN device.
- Adds exception for XRay outbound address (basically your VPN server IP).
- Tunnel is created to process all incoming IP packets via TCP/IP stack. All outbound traffic is routed through the XRay inbound proxy and all incoming packets are routed back via TUN device.
## 📝 TODO
- [ ] Add IPV6 support
## 🎯 Motivation
There are no available XRay clients implementations in Go on Github, so I decided to do it myself. The attempt proved to be successfull and I wanted to share my findings in a complete and working VPN client.
## Credits
- https://github.com/xtls/xray-core
- https://github.com/lilendian0x00/xray-knife
- https://github.com/jackpal/gateway