A high-performance, self-hosted quality assurance toolkit for VPN proxy configurations. Namira Core validates, benchmarks, and ranks VMess, VLESS, Trojan, and Shadowsocks connections with real TCP handshakes and latency measurements.

• Multi-Protocol Support: Validates VMess, VLESS, Shadowsocks, and Trojan VPN configurations
• Real Connection Testing: Uses real TCP handshakes, not just pings
• High Concurrency: Dynamically adjusts concurrent connection limits based on system resources
• API Server: RESTful API for checking VPN configurations
• Notification System: Integrated Telegram notifications for valid configurations
• Worker Pool: Efficient job processing with configurable worker pools
• Redis Integration: Persistent storage and caching of results
• GitHub Integration: Automated updates to GitHub repositories with valid configurations

• Quick Start
• How It Works
• Architecture
• Requirements
• Configuration
• Installation
• API Documentation
• Example Usage
• Troubleshooting
• Project Structure
• Contributing
• License
• Acknowledgments

# Clone the repository
git clone https://github.com/NamiraNet/namira-core.git
cd namira-core

# Create .env file with your configuration
cp .env.example .env
# Edit .env with your settings

# Start the services
docker-compose up -d

Access the API at http://localhost:8080

# Build the application
make build-local

# Check VPN configurations from file
./bin/namira-core check --file proxies.txt

# Check individual configurations
./bin/namira-core check --config "vmess://..." --config "vless://..."

Namira Core processes VPN configurations through a pipeline of operations to validate their connectivity and measure performance:

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│             │    │             │    │             │    │             │    │             │
│    Input    │───►│   Parser    │───►│  Checker    │───►│  Analyzer   │───►│   Output    │
│  VPN Links  │    │             │    │             │    │             │    │   Results   │
│             │    │             │    │             │    │             │    │             │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
                         │                  │                  │
                         ▼                  ▼                  ▼
                   ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
                   │             │    │             │    │             │
                   │  Protocol   │    │    TCP      │    │  Latency    │
                   │ Extraction  │    │ Handshake   │    │ Measurement │
                   │             │    │             │    │             │
                   └─────────────┘    └─────────────┘    └─────────────┘

1. Input Processing:

   • VPN configuration links are submitted via API or CLI
   • Links are queued for processing in the worker pool

2. Parsing:

   • Each link is parsed to extract protocol-specific parameters
   • Supported protocols: VMess, VLESS, Shadowsocks, Trojan

3. Checking:

   • Real TCP handshakes are performed to verify connectivity
   • Connection timeouts and errors are handled gracefully
   • Latency is measured with multiple samples for accuracy

4. Analysis:

   • Results are analyzed to determine availability status
   • Configurations are ranked by performance
   • Metadata is enriched (location, provider, etc.)

5. Output:

   • Results are returned via API or saved to files
   • Valid configurations can be automatically:
     • Sent to Telegram channels
     • Committed to GitHub repositories
     • Stored in Redis for caching

The worker pool manages concurrency, ensuring optimal resource utilization while preventing system overload.

The application is structured with clean separation of concerns:

• Core: Central components for parsing and checking VPN configurations
• API: RESTful endpoints for submitting configuration check requests
• Worker: Background job processing for handling configuration checks
• Notify: Notification system for sending results via Telegram
• Config: Configuration management from environment variables
• Logger: Structured logging using zap

• Go 1.24+
• Redis 8.0+
• GitHub SSH key (for GitHub integration)
• Docker and Docker Compose (for containerized deployment)

The application is configured via environment variables:

1. Clone the repository:

   git clone https://github.com/NamiraNet/namira-core.git
   cd namira-core

2. Create a .env file with your configuration:

   cp .env.example .env
   # Edit .env with your preferred text editor

3. Start the services:

   make prod    # For production environment
   # OR
   make dev     # For development environment with logs

4. Check if the service is healthy:

   make health

1. Clone the repository:

   git clone https://github.com/NamiraNet/namira-core.git
   cd namira-core

2. Install dependencies:

   make install

3. Build the application:

   make build-local

4. Run the application:

   make run-local
   # OR run directly
   ./bin/namira-core api

Run make help to see all available commands:

Namira Core Makefile
Usage: make [target]

Targets:
build                Build Docker containers without starting them
build-local          Build the Go binary locally
build-release        Build optimized release binary
clean                Clean up Docker resources and build artifacts
dev                  Start development environment with Docker Compose
docker-build         Build Docker image
docker-push          Build and push Docker image
down                 Stop Docker Compose services
health               Check service health
help                 Show this help message
install              Install project dependencies
lint                 Run linters
logs                 View Docker Compose logs
prod                 Start production environment with Docker Compose
run-local            Run the application locally
test                 Run all tests / Coming Soon 
test-coverage        Run tests with coverage / Coming Soon 
up                   Start Docker Compose services
version              Show version information

The CLI provides a powerful interface for batch checking VPN configurations without requiring a full server setup.

# Show version
./bin/namira-core --version

# Display help
./bin/namira-core check --help

# Check configurations from a file
./bin/namira-core check --file proxies.txt

# Check individual configurations
./bin/namira-core check --config "vmess://..." --config "vless://..."

# Mix file and individual configs
./bin/namira-core check --file proxies.txt --config "trojan://..."

# Check all configurations in a file
./bin/namira-core check --file proxies.txt

# Check with custom concurrency and timeout
./bin/namira-core check --file proxies.txt --concurrent 20 --timeout 15s

# Check single configuration
./bin/namira-core check --config "vmess://eyJ2IjoiMiIsInBzIjoi..."

# Check multiple configurations
./bin/namira-core check \
  --config "vmess://eyJ2IjoiMiIsInBzIjoi..." \
  --config "vless://..." \
  --config "trojan://..."

# Silent mode with JSON output
./bin/namira-core check \
  --file proxies.txt \
  --format json \
  --output results.json \
  --progress false

# High concurrency for large files
./bin/namira-core check \
  --file large_proxy_list.txt \
  --concurrent 50 \
  --timeout 5s \
  --format csv \
  --output report.csv

Your input file should contain one VPN configuration per line:

vmess://eyJ2IjoiMiIsInBzIjoidGVzdCIsImFkZCI6IjEuMS4xLjEiLCJwb3J0IjoiNDQzIiwiaWQiOiJ0ZXN0LWlkIiwiYWlkIjoiMCIsInNjeSI6ImF1dG8iLCJuZXQiOiJ3cyIsInR5cGUiOiJub25lIiwiaG9zdCI6IiIsInBhdGgiOiIvIiwidGxzIjoidGxzIiwic25pIjoiIn0=
vless://[email protected]:443?encryption=none&security=tls&type=ws&path=/&host=#test
trojan://[email protected]:443?security=tls&type=tcp&headerType=none#test
ss://[email protected]:8388#test

GET /health

Returns service health status.

This endpoint accepts proxy configurations to initiate a background scanning job.

You can submit configurations in two formats:

POST /scan
Content-Type: application/json

{
  "configs": [
    "vmess://xxxxxxxxxxxxxxxxxxxx",
    "vless://yyyyyyyyyyyyyyyyyyyy"
  ]
}

POST /scan
Content-Type: text/plain

vmess://xxxxxxxxxxxxxxxxxxxx
vless://yyyyyyyyyyyyyyyyyyyy
trojan://zzzzzzzzzzzzzzzzzz

curl -X POST http://localhost:8080/scan \
  -H "Content-Type: text/plain" \
  --data-binary @proxies.txt

vmess://xxxxxxxxxxxxxxxxxxxx
vless://yyyyyyyyyyyyyyyyyyyy
trojan://zzzzzzzzzzzzzzzzzz

GET /jobs/{job_id}

# Check a few configurations quickly
./bin/namira-core check \
  --config "vmess://..." \
  --config "vless://..." \
  --format table

# Process large list with optimal settings
./bin/namira-core check \
  --file large_list.txt \
  --concurrent 30 \
  --timeout 8s \
  --format json \
  --output results.json \
  --progress

curl -X POST http://localhost:8080/scan \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: apikey" \
  -d '{"configs": ["vmess://...", "vless://..."]}'

curl -X GET -H "X-API-KEY: apikey" http://localhost:8080/jobs/{job_id}

Namira Core provides OpenAPI-compliant documentation to help you explore and interact with the API.

• docs/swagger.yaml – OpenAPI specification in YAML format
• docs/swagger.json – OpenAPI specification in JSON format
• docs/docs.go – Go-based embedded Swagger handler for serving docs via the API

Enable debug logging:

export LOG_LEVEL=debug
./bin/namira-core api
# OR
./bin/namira-core check --file proxies.txt

Contributions are welcome! Please read our Contributing Guidelines before submitting a pull request.

# Clone the repository
git clone https://github.com/NamiraNet/namira-core.git
cd namira-core

# Install dependencies
make install

# Run tests
make test

# Start development server
make dev

Distributed under the AGPL-3 License. See LICENSE for full text.

• Go community for excellent libraries and tools
• V2Ray project for providing the foundation for VPN protocol implementation

• Telegram: https://t.me/NamiraNet
• Website: https://namira-web.vercel.app
• Email: NamiraNet [at] proton.me
• GitHub Discussions: open to all "how-do-I" questions.

_{Made with ❤️ by the community using contrib.rocks}

🙏 Thank you to all the contributors who make this project possible.