https://github.com/sing-box-orbit/sing-box-orbit-node
REST API server for managing sing-box proxy instances
https://github.com/sing-box-orbit/sing-box-orbit-node
api bun hono proxy rest-api sing-box typescript vpn
Last synced: 5 months ago
JSON representation
REST API server for managing sing-box proxy instances
- Host: GitHub
- URL: https://github.com/sing-box-orbit/sing-box-orbit-node
- Owner: sing-box-orbit
- Created: 2026-01-10T06:21:38.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-10T12:50:09.000Z (5 months ago)
- Last Synced: 2026-01-11T03:00:02.561Z (5 months ago)
- Topics: api, bun, hono, proxy, rest-api, sing-box, typescript, vpn
- Language: TypeScript
- Size: 59.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# sing-box-orbit-node
[](https://github.com/sing-box-orbit/sing-box-orbit-node/actions/workflows/ci.yml)
[](https://sing-box-orbit.github.io/sing-box-orbit-node/)
[](https://opensource.org/licenses/MIT)
REST API server for remote management of [sing-box](https://sing-box.sagernet.org/) โ universal proxy platform.
**[๐ท๐บ ะ ัััะบะฐั ะฒะตััะธั](README.ru.md)**
## Features
- Start/stop/reload sing-box process
- **Auto-restart on crash** with exponential backoff
- Monitor server status and health
- Real-time log viewing
- Configuration validation before startup
- Automatic OpenAPI documentation
- Optional API-key authentication
- **Rate limiting** for DDoS protection
## Requirements
- [Bun](https://bun.sh/) >= 1.0
- sing-box binary (downloaded automatically)
## Quick Start
```bash
# Clone repository
git clone
cd sing-box-orbit-node
# Install dependencies
bun install
# Download sing-box binary for your platform
bun run setup
# Copy and configure environment variables
cp .env.example .env
# Create sing-box configuration
mkdir -p data
# Place your config.json in ./data/config.json
# Start in development mode
bun run dev
```
## Scripts
| Command | Description |
|---------|-------------|
| `bun run dev` | Start with hot-reload |
| `bun run start` | Start in production mode |
| `bun run build` | Build standalone executable |
| `bun run setup` | Download sing-box binary |
| `bun run lint` | Check code (Biome) |
| `bun run lint:fix` | Auto-fix lint errors |
| `bun run format` | Format code |
| `bun run typecheck` | TypeScript type checking |
| `bun run test` | Run tests |
| `bun run test:watch` | Run tests in watch mode |
| `bun run test:coverage` | Run tests with coverage report |
## Configuration
Environment variables (`.env`):
| Variable | Default | Description |
|----------|---------|-------------|
| `NODE_ENV` | development | Environment mode |
| `HOST` | 0.0.0.0 | Server bind address |
| `PORT` | 3333 | Server port |
| `API_KEY` | โ | API key for authentication |
| `SINGBOX_BIN` | ./bin/sing-box | Path to sing-box binary |
| `SINGBOX_CONFIG_PATH` | ./data/config.json | Config file path |
| `SINGBOX_WORKING_DIR` | ./data | Working directory |
| `SINGBOX_AUTO_RESTART` | true | Auto-restart on crash |
| `SINGBOX_RESTART_DELAY` | 1000 | Initial restart delay (ms) |
| `SINGBOX_MAX_RESTARTS` | 5 | Max restarts within window |
| `SINGBOX_RESTART_WINDOW` | 60000 | Time window for restart limit (ms) |
| `RATE_LIMIT_ENABLED` | true | Enable rate limiting |
| `RATE_LIMIT_MAX_REQUESTS` | 100 | Max requests per window |
| `RATE_LIMIT_WINDOW_MS` | 60000 | Time window (ms) |
| `LOG_LEVEL` | info | Log level |
## API
Base URL: `http://localhost:3333`
If `API_KEY` is set, requests must include header `Authorization: Bearer ` or `X-API-Key: `.
Interactive documentation available at `http://localhost:3333/docs`
## Docker
### Using Docker Compose (recommended)
Create `docker-compose.yml`:
```yaml
services:
sing-box-orbit-node:
image: ghcr.io/sing-box-orbit/sing-box-orbit-node:latest
container_name: sing-box-orbit-node
network_mode: host
restart: unless-stopped
environment:
- API_KEY=your-secret-api-key
- LOG_LEVEL=info
volumes:
- ./data:/etc/sing-box
- ./logs:/app/data/logs
```
```bash
mkdir -p data logs
docker compose up -d
```
> **Note:** Default configuration is created automatically on first start if `config.json` doesn't exist.
### Using Docker directly
```bash
docker run -d \
--name sing-box-orbit-node \
-p 3333:3333 \
-v $(pwd)/data:/etc/sing-box \
-v $(pwd)/logs:/app/data/logs \
-e API_KEY=your-secret-key \
ghcr.io/sing-box-orbit/sing-box-orbit-node:latest
```
### Volume paths
| Host path | Container path | Description |
|-----------|----------------|-------------|
| `./data` | `/etc/sing-box` | sing-box config and working directory |
| `./logs` | `/app/data/logs` | Application logs |
### Health check
The `/health` endpoint is publicly accessible (no authentication required) for container orchestration compatibility.
## Tech Stack
- **Runtime**: [Bun](https://bun.sh/)
- **Framework**: [Hono](https://hono.dev/)
- **API Schema**: [fets](https://github.com/ardatan/feTS) + [TypeBox](https://github.com/sinclairzx81/typebox)
- **Docs**: [Scalar](https://scalar.com/)
- **Linter**: [Biome](https://biomejs.dev/)
## License
MIT