Một trang gom đủ: lấy API token, gọi REST API, chạy tunnel trong Docker / docker-compose / Kubernetes / CI, và cho AI agent tự dùng qua MCP. Mọi thứ chỉ cần ssh + 1 token — không SDK, không cài agent riêng.
Mở Dashboard ▸ API tokens. Mỗi tài khoản có sẵn một token mặc định (xem lại được bất cứ lúc nào); bấm tạo token để có thêm token riêng cho từng máy/CI/agent — chuỗi entry_… của token mới chỉ hiện một lần.
Gắn vào header Authorization theo chuẩn Bearer:
Trả về tài khoản, hạn mức, domain tunnel và cổng SSH:
Base URL https://app.entry.io.vn · JSON · auth Authorization: Bearer entry_… (sai/thu hồi token → 401).
| Việc | Endpoint |
|---|---|
| Tài khoản, hạn mức | GET /v1/me |
| Tunnel đang chạy (+ số slot còn lại) | GET /v1/tunnels |
| Cưỡng ép đóng tunnel đang chạy | POST /v1/tunnels/:subdomain/close |
| Mức dùng 30 ngày (bytes, requests) | GET /v1/usage |
| SSH key: xem / thêm / xoá | GET POST /v1/ssh-keys · DEL /v1/ssh-keys/:id |
| Subdomain giữ chỗ (tên cố định) | GET POST /v1/reserved · DEL /v1/reserved/:id |
| Giới hạn IP cho subdomain (allowlist) | GET /v1/tunnel-acl · PUT DEL /v1/tunnel-acl/:subdomain |
| DDNS: xem / tạo / xoá / xoay token | GET POST /v1/ddns · DEL /v1/ddns/:pid · POST /v1/ddns/:pid/rotate-token |
| Mạng riêng (VPN): thiết bị, trạng thái | GET /v1/vpn/devices · /v1/vpn/status |
| Cổng TCP public còn trống | GET /v1/tcp-pool |
| Token: xem / tạo / xoá | GET POST /v1/tokens · DEL /v1/tokens/:id |
| Thống kê nền tảng (không cần auth) | GET /v1/stats |
Thêm SSH key của máy (để máy đó mở được tunnel):
Giữ chỗ subdomain cố định rồi mở tunnel vào đúng tên đó:
Cưỡng ép đóng tunnel đang chạy (máy cũ treo, đang giữ mất tên). Mặc định mode:"route" — chỉ đóng đúng tên đó, phiên SSH của máy vẫn sống; mode:"client" ngắt cả phiên SSH (mọi tunnel của máy đó rớt theo, response báo also_closed):
403.route (mặc định) = tắt hẳn, KHÔNG tự mở lại. sish gỡ listener nhưng phiên SSH của máy vẫn sống, nên dịch vụ ngầm 24/7 không biết mà kết nối lại. Muốn mở lại phải restart dịch vụ trên máy đó (systemctl restart entry-tunnel · Windows: Start-ScheduledTask -TaskName entry-tunnel-<tên>).client = ngắt phiên SSH → máy chạy ngầm TỰ kết nối lại sau ~5–15s và lấy lại tên. Dùng khi muốn reset kết nối treo, không phải để đóng hẳn. Muốn chặn hẳn một máy: xoá SSH key của nó, hoặc đặt IP allowlist cho subdomain (bên dưới).Chỉ cho vài IP vào subdomain (allowlist — hợp cho staging nội bộ):
/v1/tunnels lấy dữ liệu qua reconciler chạy mỗi ~5 giây — tunnel vừa mở có thể chưa xuất hiện ngay. Đừng poll gắt, đợi vài giây rồi gọi lại.Có image sẵn nguyendinhsen/entry-tunnel (Alpine + autossh, chạy non-root, tự reconnect khi rớt mạng). Nó chỉ cần SSH private key và TARGET = host:port của service cần đưa ra.
Chạy nhanh — đưa app đang chạy ở cổng 3000 trên host ra internet:
docker-compose — tunnel làm sidecar cho service trong cùng network (trỏ thẳng tên service):
| Biến môi trường | Mặc định | Ý nghĩa |
|---|---|---|
TARGET | — bắt buộc | service cần expose: web:80, host.docker.internal:3000, svc.ns.svc:8080 |
SUBDOMAIN | rỗng | tên cố định (nên giữ chỗ trước qua API/Dashboard); rỗng = ngẫu nhiên |
MODE | http | http (web, có HTTPS) hoặc tcp (Postgres, SSH… → cấp 1 cổng public) |
KEY_PATH | /keys/id_ed25519 | chỗ mount private key |
ENTRY_HOST / ENTRY_SSH_PORT | entry.io.vn / 2222 | đổi khi tự host |
EXTRA_COMMAND | rỗng | nâng cao, vd alias riêng tư tcp-aliases-allowed-users=SHA256:… |
/tmp và chmod 600 nên mount :ro vẫn chạy. Nếu bạn tự viết Dockerfile gọi ssh trực tiếp, phải làm bước này — không thì ssh báo UNPROTECTED PRIVATE KEY FILE (volume read-only không chmod được).KEY_PATH=/run/secrets/entry_key.Cùng image đó, đóng gói thành Helm chart entry-tunnel — đưa một Service trong cụm ra HTTPS không cần LoadBalancer / Ingress công / IP public.
TCP (vd Postgres nội bộ): thêm --set tunnel.mode=tcp --set tunnel.target=postgres.db.svc:5432. Một tunnel = một Service; nhiều Service → nhiều release.
Ví dụ GitHub Actions: dựng app rồi mở tunnel để chạy test E2E từ ngoài / gửi preview URL cho reviewer. Key nằm trong repo secret ENTRY_SSH_KEY (public key của nó đã thêm vào tài khoản).
-N — sish cần một remote command để đăng ký tunnel, có -N thì tunnel không được tạo. Chạy nền thì dùng "sleep infinity" & như trên.MCP (Model Context Protocol) là chuẩn để agent gọi tool. MCP server của entry.io.vn chạy stdio ngay trên máy agent, auth bằng API token ở bước 1 — cho Claude (Code/Desktop) hay bất kỳ MCP client nào tự mở tunnel, quản DDNS / SSH key / subdomain / VPN.
Claude Code — một lệnh:
Claude Desktop — claude_desktop_config.json:
Cần Node ≥ 18. Biến tuỳ chọn: ENTRY_BASE_URL (mặc định https://app.entry.io.vn), ENTRY_SSH_HOST (entry.io.vn), ENTRY_SSH_PORT (2222) — đổi khi tự host.
23 tool agent gọi được:
| Nhóm | Tool |
|---|---|
| Tunnel | entry_tunnel_open, entry_tunnel_close, entry_tunnels, entry_tunnels_local, entry_tunnel_acl_get/_set/_clear, entry_tcp_pool |
| DDNS | entry_ddns_list, entry_ddns_create, entry_ddns_delete, entry_ddns_update_ip |
| SSH key | entry_ssh_keys, entry_ssh_key_add, entry_ssh_key_delete |
| Subdomain | entry_reserved, entry_reserve_subdomain, entry_reserved_delete |
| VPN | entry_vpn_devices, entry_vpn_status |
| Tài khoản | entry_whoami, entry_stats, entry_usage |
entry_tunnel_open spawn ssh -R nền trên máy chạy agent → máy đó cần có ssh và SSH key đã thêm vào tài khoản (agent tự thêm được bằng entry_ssh_key_add). Tunnel sống tới khi entry_tunnel_close hoặc tắt MCP.Tạo tên qua API (trả về fqdn + token + update_url):
Cập nhật IP theo giao thức DynDNS (router cắm thẳng, hoặc cron trên máy) — Basic auth: user = label, pass = token. Bỏ myip thì server lấy IP nguồn của request:
POST /v1/ddns/:pid/rotate-token để xoay.-N. sish cần remote command để đăng ký tunnel. Đúng: ssh -p 2222 -R 80:localhost:3000 entry.io.vn; chạy nền: thêm "sleep infinity". Có -N → không in URL, không forward.https:// dù sish in ra http:// (sish không làm TLS — nginx mới làm; http:// sẽ 301). Script/CI hãy gọi thẳng https://.UNPROTECTED PRIVATE KEY FILE trong container → volume :ro không chmod được. Copy ra rồi chmod 600: cp /keys/id /tmp/k && chmod 600 /tmp/k. Image entry-tunnel đã làm sẵn.Permission denied (publickey) → public key của máy/CI đó chưa có trong tài khoản. Thêm qua Dashboard ▸ Public SSH Keys hoặc POST /v1/ssh-keys./v1/tunnels chưa thấy tunnel mới → dữ liệu đồng bộ qua reconciler ~5s, không realtime. Đợi rồi gọi lại.limits trong /v1/me. Tunnel TCP lấy cổng từ pool chung (/v1/tcp-pool); cần cổng ổn định lâu dài → dùng alias + ProxyJump hoặc mạng riêng (VPN).