Trả lời nhanh: ngrok là công cụ tạo đường hầm (tunnel) đưa một dịch vụ đang chạy trên localhost ra Internet qua một URL HTTPS công khai. Bạn cài agent, thêm authtoken lấy từ dashboard của chính mình, rồi chạy lệnh ngrok http 3000. Cách này hợp để test webhook, demo cho khách hoặc gọi API từ điện thoại, không dùng thay hosting thật.
Điểm chính
- Chỉ cần 3 bước: cài ngrok, chạy ngrok config add-authtoken, rồi ngrok http kèm số cổng của ứng dụng.
- Giao diện kiểm tra tại http://localhost:4040 cho xem lại và gửi lại (replay) từng request, rất tiện khi gỡ lỗi webhook.
- Bản miễn phí có 1 dev domain cố định, 1 GB dữ liệu và 20.000 request HTTP mỗi tháng, kèm trang cảnh báo trước khi người xem mở bằng trình duyệt.
- URL ngrok ai cũng truy cập được: không mở dịch vụ nhạy cảm, bật basic auth hoặc OAuth, tắt agent khi xong việc.
- Một số mạng công ty chặn tên miền ngrok vì công cụ này từng bị lạm dụng cho phishing; khi đó hãy cân nhắc Cloudflare Tunnel, Tailscale Funnel hoặc localtunnel.
Mục lục
- Ngrok là gì và hoạt động thế nào?
- Khi nào bạn cần public localhost bằng ngrok?
- Cách cài đặt ngrok trên macOS, Windows và Linux
- Thêm authtoken cho ngrok
- Cách dùng ngrok: chạy lệnh ngrok http 3000
- Xem và gửi lại request ở giao diện localhost:4040
- Ngrok webhook: quy trình test từ đầu đến cuối
- Domain tĩnh trên ngrok hoạt động ra sao?
- Giới hạn của ngrok bản miễn phí
- Bảo mật khi dùng ngrok: những việc phải làm
- Vì sao mạng công ty chặn ngrok?
- Giải pháp thay thế ngrok
- Câu hỏi thường gặp
Ngrok là gì và hoạt động thế nào?
ngrok là dịch vụ reverse proxy dạng đường hầm. Trên máy bạn có một chương trình nhỏ gọi là agent. Agent chủ động mở kết nối ra ngoài (outbound) tới hạ tầng của ngrok. Phía ngrok cấp cho bạn một URL công khai, ví dụ dạng ten-duoc-cap.ngrok-free.app. Mọi request gửi tới URL đó được chuyển qua đường hầm về đúng cổng trên máy bạn, chẳng hạn localhost:3000.
Điểm quan trọng là kết nối đi từ trong ra ngoài. Bạn không cần mở port trên router (port forwarding), không cần IP tĩnh, không cần sửa cấu hình mạng. Theo tài liệu chính thức của ngrok, mọi endpoint đều có mã hoá TLS sẵn, nên URL bạn nhận được là HTTPS ngay từ đầu. Điều này có ích vì nhiều dịch vụ chỉ chấp nhận gửi webhook tới địa chỉ HTTPS.
Khi bạn tắt agent, URL ngừng hoạt động. Vì vậy ngrok là công cụ cho giai đoạn phát triển và thử nghiệm. Nó không thay cho máy chủ thật hay dịch vụ hosting khi sản phẩm chạy chính thức.

Khi nào bạn cần public localhost bằng ngrok?
Ứng dụng trên localhost chỉ máy bạn gọi được. Các tình huống dưới đây cần một bên ngoài Internet gọi vào.
Test webhook thanh toán và chatbot
Webhook là cơ chế một dịch vụ chủ động gửi request HTTP tới máy chủ của bạn khi có sự kiện. Ví dụ cổng thanh toán báo đơn đã trả tiền. Nếu bạn chưa rõ khác biệt giữa hai cách tích hợp này, xem bài API và webhook khác nhau thế nào. Bên gửi webhook nằm ngoài Internet nên không thể gọi tới localhost. Với ngrok, bạn dán URL công khai vào phần cấu hình webhook của dịch vụ, sau đó đặt breakpoint và gỡ lỗi code ngay trên máy mình.
Cách này cũng hợp khi bạn dựng quy trình tự động trên máy, chẳng hạn chạy n8n tự host ở localhost và cần một dịch vụ bên ngoài kích hoạt node Webhook.
Demo cho khách hoặc đồng nghiệp
Muốn khách xem thử giao diện mà chưa deploy lên staging, bạn chỉ cần gửi URL ngrok. Lưu ý bản miễn phí hiện một trang cảnh báo trước khi người xem vào trang bằng trình duyệt, phần giới hạn bên dưới có giải thích chi tiết.
Gọi API từ điện thoại hoặc thiết bị khác
Khi làm app di động, bạn cần app trên điện thoại thật gọi tới backend đang chạy trên laptop. Nếu hai thiết bị không cùng mạng, hoặc app bắt buộc HTTPS, URL ngrok giải quyết nhanh. Nếu bạn mới làm quen khái niệm này, bài API là gì giải thích nền tảng trước khi bạn thử.
Cách cài đặt ngrok trên macOS, Windows và Linux
Trước tiên, đăng ký tài khoản miễn phí trên trang ngrok.com. Sau đó cài agent theo hệ điều hành. Các lệnh dưới đây lấy theo trang Quickstart chính thức của ngrok. Cách cài có thể thay đổi theo phiên bản, nên khi gặp lỗi hãy đối chiếu lại tài liệu gốc.
- macOS: cài qua Homebrew bằng lệnh
brew install ngrok. - Windows: cài từ Microsoft Store, hoặc tải bản cài trực tiếp ở trang download của ngrok rồi giải nén.
- Linux (Debian, Ubuntu): thêm kho phần mềm (repository) của ngrok theo hướng dẫn trên trang Quickstart, sau đó chạy
sudo apt install ngrok. Bạn cũng có thể tải file nén từ trang download. - Kiểm tra: mở terminal và chạy
ngrok help. Nếu thấy danh sách lệnh là đã cài xong.
Chỉ tải ngrok từ trang chính thức, Homebrew, kho apt của ngrok hoặc Microsoft Store. Các bản “ngrok full”, “ngrok không giới hạn” chia sẻ trên diễn đàn hay nhóm chat có thể đã bị cài mã độc. Một agent giả mạo chạy trên máy bạn có quyền nhìn thấy toàn bộ dữ liệu đi qua đường hầm.
Thêm authtoken cho ngrok
Authtoken là chuỗi bí mật gắn với tài khoản của bạn. Agent cần nó để kết nối tới ngrok. Cách làm:
- Đăng nhập dashboard ngrok bằng tài khoản của chính bạn.
- Vào mục Getting Started, chọn phần Your Authtoken và sao chép chuỗi token hiển thị ở đó. Giao diện có thể khác theo phiên bản.
- Trong terminal, chạy lệnh
ngrok config add-authtoken TOKEN_CUA_BAN, thay TOKEN_CUA_BAN bằng chuỗi vừa sao chép.
Lệnh này lưu token vào file cấu hình của ngrok, nên bạn chỉ cần làm một lần trên mỗi máy. Hãy coi authtoken như mật khẩu. Không commit lên Git, không gửi qua chat, vì ai có token đều mở được đường hầm dưới tài khoản bạn. Nếu lỡ để lộ, vào dashboard tạo token mới và thu hồi token cũ.
Cách dùng ngrok: chạy lệnh ngrok http 3000
Giả sử ứng dụng của bạn (Node.js, Laravel, Django hay bất kỳ framework nào) đang chạy ở cổng 3000. Làm theo các bước sau:
- Khởi động ứng dụng và mở thử http://localhost:3000 để chắc nó chạy được.
- Mở một cửa sổ terminal khác và chạy
ngrok http 3000. Nếu ứng dụng dùng cổng khác, thay 3000 bằng cổng đó, ví dụngrok http 8080. - Agent hiện một bảng điều khiển trong terminal. Tìm dòng Forwarding. Ví dụ minh hoạ: Forwarding https://ten-duoc-cap.ngrok-free.app chuyển tới http://localhost:3000. Giao diện có thể khác theo phiên bản.
- Sao chép URL HTTPS ở dòng Forwarding và mở thử trên điện thoại dùng 4G để kiểm tra từ bên ngoài.
- Khi xong, quay lại terminal và nhấn Ctrl + C để tắt đường hầm.
Xem và gửi lại request ở giao diện localhost:4040
Khi agent chạy, nó mở một giao diện kiểm tra cục bộ (web inspection interface) tại http://localhost:4040. Tài liệu Agent API của ngrok cho biết API cục bộ cũng nằm ở địa chỉ này, cụ thể là http://127.0.0.1:4040/api. Nếu bạn đổi tham số web_addr trong file cấu hình thì địa chỉ cũng đổi theo.
Tại giao diện này bạn xem được:
- Danh sách từng request đi qua đường hầm: phương thức, đường dẫn, mã trạng thái trả về và thời gian xử lý.
- Toàn bộ header và body của cả request lẫn response. Dữ liệu JSON, XML, form được định dạng cho dễ đọc.
- Nút Replay để gửi lại đúng request đó tới ứng dụng của bạn.
Replay đặc biệt quý khi test webhook. Thay vì tạo giao dịch thử mới, bạn sửa code, bấm gửi lại request cũ và xem kết quả ngay. ngrok còn có Traffic Inspector trên dashboard với chức năng tương tự, cho phép chỉnh header, tham số hoặc body trước khi gửi lại.
Giao diện 4040 hiển thị nguyên văn dữ liệu, gồm cả token, cookie và thông tin khách hàng nếu có. Khi chia sẻ màn hình hoặc chụp ảnh gửi đồng nghiệp, hãy che các trường này. Nếu không cần ghi lại request, chạy agent với tham số –inspect=false để tắt tính năng này.
Ngrok webhook: quy trình test từ đầu đến cuối
Dưới đây là quy trình gợi ý khi bạn tích hợp webhook của một cổng thanh toán hay nền tảng chatbot. Tên menu cụ thể tuỳ từng dịch vụ.
- Viết route nhận webhook trong ứng dụng, ví dụ đường dẫn /webhook/payment, và cho nó ghi log toàn bộ body nhận được.
- Chạy ứng dụng ở cổng 3000, rồi chạy
ngrok http 3000. - Ghép URL công khai với đường dẫn route, ví dụ minh hoạ: https://ten-duoc-cap.ngrok-free.app/webhook/payment.
- Dán URL này vào trang cấu hình webhook của dịch vụ, ở môi trường thử nghiệm (sandbox) chứ không phải môi trường thật.
- Tạo một sự kiện thử, mở localhost:4040 để xem request có tới không và ứng dụng trả mã gì.
- Kiểm tra chữ ký (signature) của webhook trong code. Thiếu bước này, ai biết URL cũng giả mạo được sự kiện.
- Khi chuyển lên máy chủ thật, nhớ đổi URL webhook sang tên miền chính thức.
Một điểm dễ nhầm: trang cảnh báo của bản miễn phí chỉ hiện với lưu lượng HTML từ trình duyệt. Theo trang giới hạn của ngrok, nó không ảnh hưởng tới client gọi API hay gọi bằng chương trình. Webhook từ dịch vụ bên ngoài vì thế vẫn tới thẳng ứng dụng của bạn.
Domain tĩnh trên ngrok hoạt động ra sao?
Theo trang giới hạn bản miễn phí của ngrok, mỗi tài khoản được tự động cấp 1 dev domain, ví dụ dạng ten-duoc-cap.ngrok-free.app, và tên này giữ nguyên qua các lần khởi động lại agent. Bạn chỉ cần đăng ký URL webhook một lần.
Bạn xem dev domain của mình trong dashboard. Tham số –url dùng để chọn URL cho endpoint. Tuy nhiên, tài liệu Quickstart ghi rõ việc tuỳ biến tên miền bằng –url là tính năng của gói trả phí. Tên miền riêng, tên miền dạng wildcard hay đặt trước nhiều domain cố định đều cần nâng cấp.
Giới hạn của ngrok bản miễn phí
Số liệu dưới đây lấy từ trang Free plan limits trong tài liệu chính thức của ngrok, kiểm tra vào tháng 11/2026. ngrok có thể thay đổi chính sách, nên trước khi dùng cho dự án quan trọng hãy xem lại trang này và mục Usage trên dashboard.
| Hạng mục | Bản miễn phí |
|---|---|
| Dữ liệu truyền ra | 1 GB mỗi tháng |
| Request HTTP | 20.000 mỗi tháng, tối đa 4.000 mỗi phút |
| Kết nối TCP | 5.000 mỗi tháng, tối đa 100 mỗi phút |
| Endpoint chạy đồng thời | Tối đa 3 |
| Agent chạy đồng thời | 3 |
| Tên miền | 1 dev domain tự cấp, không dùng được tên miền riêng |
| Người dùng OAuth/OIDC | 3 người mỗi tháng |
| Xác minh webhook | 500 lần mỗi tháng |
| Quy tắc Traffic Policy | 5 quy tắc mỗi policy |
| Trang cảnh báo trình duyệt | Có, với lưu lượng HTML |
Các mức này thường đủ để test webhook hay demo, nhưng file lớn sẽ nhanh hết 1 GB. Trang cảnh báo hiện trước mọi lưu lượng HTML từ trình duyệt. Người xem bấm Visit thì trình duyệt lưu cookie và không hiện lại trong 7 ngày với domain đó. Nếu bạn tự gọi qua code, gửi header ngrok-skip-browser-warning sẽ bỏ qua trang này.
Riêng đường hầm TCP, từ tháng 6/2024 ngrok yêu cầu tài khoản thêm thẻ tín dụng hoặc thẻ ghi nợ để xác minh danh tính, kể cả ở bản miễn phí. Theo bài thông báo của ngrok, lý do là chống lạm dụng cho các chiến dịch mã độc, và người dùng miễn phí không bị trừ tiền.
Bảo mật khi dùng ngrok: những việc phải làm
URL ngrok là công khai. Bất kỳ ai có link đều vào được, và các công cụ quét tự động cũng có thể tìm thấy nó. Hãy làm các việc sau:
- Không mở dịch vụ nhạy cảm: không đưa ra ngoài trang quản trị cơ sở dữ liệu, bảng điều khiển router, trang admin chưa có mật khẩu, dịch vụ remote desktop hay thư mục chứa dữ liệu khách hàng.
- Dùng dữ liệu giả: ứng dụng chạy qua ngrok nên kết nối tới cơ sở dữ liệu thử, không phải bản sao dữ liệu thật.
- Bật xác thực: thêm basic auth hoặc OAuth bằng Traffic Policy, xem ví dụ bên dưới.
- Kiểm tra chữ ký webhook: đừng tin mọi request chỉ vì nó tới đúng đường dẫn. Nguyên tắc chung xem thêm ở bài bảo mật API là gì.
- Tắt khi xong: nhấn Ctrl + C ngay sau buổi test, không để đường hầm chạy qua đêm khi không cần.
Bật basic auth hoặc OAuth bằng Traffic Policy
Các cờ cũ như –basic-auth và –oauth đã bị đánh dấu ngừng hỗ trợ (deprecated) trong tài liệu CLI. ngrok khuyến nghị dùng Traffic Policy. Bạn tạo file policy.yml với nội dung như ví dụ minh hoạ sau:
on_http_request:
- actions:
- type: basic-auth
config:
credentials:
- "demo:mat-khau-dai-it-nhat-8-ky-tu"
Sau đó chạy ngrok http 3000 --traffic-policy-file policy.yml. Người truy cập phải nhập đúng tên và mật khẩu mới vào được. Theo tài liệu action basic-auth, bạn khai báo tối đa 10 cặp tên:mật khẩu, mật khẩu dài từ 8 đến 128 ký tự.
Muốn chỉ cho người có email công ty vào, dùng action oauth với nhà cung cấp như Google, kết hợp điều kiện lọc theo đuôi email. Tài liệu Authentication của ngrok có ví dụ đầy đủ. Lưu ý bản miễn phí chỉ cho 3 người dùng OAuth mỗi tháng, và ứng dụng OAuth do ngrok quản lý chỉ nên dùng khi thử nghiệm.
Vì sao mạng công ty chặn ngrok?
Vì dễ dùng và có HTTPS sẵn, ngrok từng bị kẻ xấu lạm dụng. Các hãng bảo mật như Cyble đã ghi nhận chiến dịch phishing dùng URL ngrok để dựng trang đăng nhập giả. Chính ngrok cũng thừa nhận có kẻ xấu dùng nền tảng cho mã độc và cho biết đã khoá các tài khoản phishing.
Hệ quả là nhiều doanh nghiệp chặn tên miền ngrok trên firewall hoặc proxy, hoặc cấm cài agent trên máy công ty. Lý do là một đường hầm outbound có thể vượt qua kiểm soát truy cập từ ngoài vào, trái với nguyên tắc của mô hình zero trust. Nếu máy bạn thuộc công ty, hãy hỏi bộ phận IT trước khi dùng ngrok. Ngược lại, bạn cũng nên cảnh giác khi nhận một đường link có đuôi ngrok-free.app yêu cầu đăng nhập ngân hàng, ví điện tử hay email.
Giải pháp thay thế ngrok
Nếu ngrok bị chặn hoặc giới hạn miễn phí không đủ, bạn có thể cân nhắc ba công cụ sau. Mỗi công cụ có đánh đổi riêng.
| Công cụ | Lệnh ví dụ | Ưu điểm | Hạn chế |
|---|---|---|---|
| Cloudflare Tunnel (Quick Tunnel) | cloudflared tunnel –url http://localhost:3000 | Không cần tài khoản hay tên miền, URL dạng trycloudflare.com | URL tạm thời, không cam kết uptime, tối đa 200 request đồng thời, không hỗ trợ Server-Sent Events |
| Tailscale Funnel | tailscale funnel 3000 | Gắn với mạng Tailscale sẵn có, URL theo tên miền ts.net của tailnet | Đang ở giai đoạn beta, phải bật MagicDNS, HTTPS và quyền funnel trong policy, có giới hạn băng thông không chỉnh được |
| localtunnel | npx localtunnel –port 3000 | Mã nguồn mở, cài qua npm, có thể xin subdomain theo ý | Phụ thuộc máy chủ cộng đồng, độ ổn định không đảm bảo, ít tính năng kiểm tra request |
Các thông tin trên lấy từ tài liệu chính thức của Cloudflare, trang hướng dẫn Funnel của Tailscale và trang GitHub của localtunnel. Nếu có tên miền riêng trên Cloudflare, bạn có thể tạo tunnel cố định thay cho Quick Tunnel. Các nguyên tắc bảo mật ở phần trên áp dụng cho mọi công cụ đường hầm.

Câu hỏi thường gặp
Ngrok có miễn phí không?
Có. Bản miễn phí cho 1 dev domain cố định, 1 GB dữ liệu và 20.000 request HTTP mỗi tháng, tối đa 3 endpoint chạy cùng lúc. Bản này có trang cảnh báo với lưu lượng HTML từ trình duyệt. Tên miền riêng, bỏ trang cảnh báo và hạn mức cao hơn cần gói trả phí.
Lệnh ngrok http 3000 báo lỗi xác thực thì làm sao?
Thường là bạn chưa thêm authtoken hoặc token đã bị thu hồi. Vào dashboard ngrok, sao chép lại token của chính bạn và chạy ngrok config add-authtoken kèm token đó. Nếu vẫn lỗi, kiểm tra mạng của bạn có chặn tên miền ngrok không.
Ngrok có an toàn không?
Bản thân kết nối được mã hoá TLS. Rủi ro nằm ở chỗ URL là công khai. Nếu bạn mở trang quản trị không mật khẩu hay dữ liệu thật, người lạ có thể truy cập. Hãy bật basic auth hoặc OAuth, dùng dữ liệu thử, kiểm tra chữ ký webhook và tắt đường hầm khi xong.
Có dùng ngrok để chạy website chính thức được không?
Không nên. Website sẽ ngừng khi máy bạn tắt, mất mạng hoặc agent dừng. Bản miễn phí còn giới hạn dung lượng và hiện trang cảnh báo. Khi sản phẩm chạy thật, hãy triển khai lên máy chủ, VPS hoặc dịch vụ hosting.
Vì sao webhook không tới được ứng dụng dù ngrok vẫn chạy?
Mở localhost:4040 để xem. Nếu không có request nào, kiểm tra URL đã dán vào dịch vụ có đúng dev domain và đường dẫn route không. Nếu request tới nhưng ứng dụng trả lỗi 4xx hoặc 5xx, xem phần response trong giao diện và log ứng dụng, sửa code rồi bấm Replay để thử lại.