git404hub

what is mg-koyeb fr?

zzzhhh1/mg-koyeb — explained in plain English

Analysis updated 2026-05-18

105ShellAudience · developerComplexity · 2/5LicenseSetup · moderate

tl;dr

Step-by-step recipe to run a single VLESS proxy in a Docker container on Koyeb's free tier, fronted by a Cloudflare tunnel so the free instance stays awake.

vibe map

mindmap
  root((mg-Koyeb))
    Inputs
      UUID
      Tunnel token
      Subdomain
    Outputs
      Docker image
      VLESS link
      Runtime logs
    Use Cases
      Personal relay
      Learn containers
      Free hosting
    Tech Stack
      Docker
      Alpine
      sing-box
      cloudflared
      supervisord

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

what do people make with this?

VIBE 1

Run a single private VLESS relay on Koyeb's free Nano instance with a Cloudflare tunnel.

VIBE 2

Keep a free container awake using the Cloudflare tunnel heartbeat instead of cron pings.

VIBE 3

Read the VLESS connection link directly from Koyeb runtime logs after first boot.

VIBE 4

Study a small two-process container managed by supervisord as a distributed-architecture exercise.

what's the stack?

DockerAlpinesing-boxcloudflaredsupervisord

how it stacks up fr

zzzhhh1/mg-koyebhypnguyen1209/offensive-claudeobra/smallest-agent
Stars105106103
LanguageShellShellShell
Setup difficultymoderateeasyeasy
Complexity2/53/52/5
Audiencedeveloperdeveloperdeveloper

Figures from each repo's GitHub metadata at analysis time.

how do i run it?

Difficulty · moderate time til it works · 30min

Needs a Cloudflare account with Zero Trust enabled and a Koyeb free-tier service, the four env vars must be set before deploy.

MIT license, very permissive, but the README forbids commercial resale.

in plain english

This project, written mostly in Chinese, is a step-by-step recipe for running a single private network relay on the free tier of a hosting service called Koyeb, with traffic routed through a Cloudflare tunnel. It uses the VLESS protocol, which is a way of forwarding network traffic, and packages everything inside a small Docker container so a beginner can copy the config files and follow along without writing code. The author frames it as a learning project for distributed container architecture, and says it is not for commercial use. The author claims three main improvements over older guides. First, the secret key, called a UUID, is never written into the public repository. Instead, the container reads it from a Koyeb environment variable at startup, so the repo can stay public without exposing anything sensitive. Second, two processes run inside one Alpine Linux container, managed by supervisord: the proxy server, sing-box, and the Cloudflare tunnel client, cloudflared. Because the tunnel sends regular heartbeat packets, the free container stays awake instead of sleeping after idle time. Third, on first boot the container reads the environment variables and prints a ready-to-import VLESS link directly into the Koyeb runtime logs, so the user can copy it in one click. The README walks through four parts. Part one is creating a public GitHub repository with four files, a config.json, an entrypoint.sh, a Dockerfile, and a supervisord.conf, and letting GitHub Actions build the container image. Part two is setting up a Cloudflare Zero Trust tunnel with a chosen subdomain, the path /blog, the HTTP service type, and the local target 127.0.0.1 on port 8080, then saving the tunnel token. Part three is creating a Koyeb service from the built Docker image, opening port 8080, choosing the free Nano instance size, and supplying four environment variables: UUID, SUBDOMAIN, TUNNEL_TOKEN, and PORT. Part four is opening the Runtime Logs after deploy, copying the printed vless:// link, and pasting it into a client app like v2rayN or Shadowrocket to test the connection. The project is shared under the MIT license, with a strong notice forbidding commercial resale.

prompts (copy fr)

prompt 1
Walk me through mg-Koyeb part one: which files go in the GitHub repo and how GitHub Actions builds the Docker image.
prompt 2
Set up a Cloudflare Zero Trust tunnel with the path /blog pointing to 127.0.0.1:8080 and save the tunnel token. Step-by-step.
prompt 3
Explain how supervisord runs sing-box and cloudflared in one Alpine container, and why the UUID is read from env at startup.
prompt 4
Modify entrypoint.sh to also print a Shadowrocket-compatible vmess link beside the vless link in the runtime logs.
prompt 5
Compare mg-Koyeb's free Nano deployment to a $5/mo Hetzner VPS for the same VLESS relay. List the trade-offs.

Frequently asked questions

what is mg-koyeb fr?

Step-by-step recipe to run a single VLESS proxy in a Docker container on Koyeb's free tier, fronted by a Cloudflare tunnel so the free instance stays awake.

What language is mg-koyeb written in?

Mainly Shell. The stack also includes Docker, Alpine, sing-box.

What license does mg-koyeb use?

MIT license, very permissive, but the README forbids commercial resale.

How hard is mg-koyeb to set up?

Setup difficulty is rated moderate, with roughly 30min to a first successful run.

Who is mg-koyeb for?

Mainly developer.

peek the repo → explain another one

This repo across BitVibe Labs

double-check against the repo, no cap.