FAQ & Documentation

Threadway is a reverse tunnel and out-of-band capture service. An alternative to ngrok or FRP. The threadway client runs next to a local app (a dev server, a CTF box, an internal tool) and gives it a public address through that server. This panel is the control plane: accounts, plans, limits, live tunnels, and security all live here.

It's built for CTFs, labs, and infrastructure you own or are authorized to test.

Two ways:

• Download a prebuilt binary from the Download page, pick your platform, no Python needed.
• Run from source (needs Python 3.9+, no third-party packages):

python3 threadway.py http 3000

On Linux/macOS the setup script installs an threadway command on your PATH; on Windows it adds an threadway shim.

Point the client at your server, sign in once, and run a tunnel:

threadway --server your-server.com --login
threadway http 3000 --subdomain

The client prints your public URL (and copies it to your clipboard). Add --save the first time to remember the server so you don't repeat it.

Either:

• threadway --login signs in with your panel username/password and caches a token. --logout clears it.
• API key, create one on your Account page (it's shown once), then pass --api-key twk_… or set THREADWAY_API_KEY. Best for scripts and CI.

HTTP (threadway http <port>) routes by hostname, so you get a friendly subdomain and it shares one set of ports with everyone. Best for web apps and webhooks.

TCP (threadway tcp <port>) gives you a raw public port: use it for SSH, databases, game servers, or any non-HTTP protocol.

Add --subdomain to an HTTP tunnel for a random one, or --subdomain myname to request a specific name:

threadway http 8080 --subdomain demo

Whether you can pick names, and how many you can reserve permanently, depends on your plan (see Plans & limits). Reserved subdomains are managed on the panel.

Yes, if your plan allows reserved ports. Request a fixed TCP port with --public-port:

threadway tcp 22 --public-port 10022

Reserve ports ahead of time on the panel; unreserved tunnels get an automatic port from the public range.

• --reconnect, auto-reconnect with backoff if the link drops (on by default for HTTP tunnels).
• --tls, encrypt the control channel to the server; add --insecure only to skip verification for a self-signed cert.
• --breakvpn, a CTF convenience that routes the tunnel outside a local VPN so the callback still reaches the server.

Yes. Either start multiple threadway processes, or describe them all in one config file and bring them up together:

threadway --config tunnels.json

The config (JSON or YAML) lists each tunnel's protocol, local port, and subdomain/port options, all sharing one login.

These work over the panel API (use a saved login or --api-key):

threadway ps                 # your tunnels, with IDs and live counts
threadway logs               # recent connections across your tunnels
threadway logs <id> -f       # follow one tunnel's connections live
threadway kill <id>          # close one (id or a unique prefix)
threadway kill --all         # close all of yours

Run the built-in health check:

threadway doctor

It checks DNS, the control port, TLS, the panel, and your API key, and tells you which step failed so you know whether it's your network, the server, or your credentials.

Add --status-line to a tunnel for a single, self-updating line showing uptime, active and total connections, bytes in/out, and reconnects, instead of a scrolling per-connection log. Handy for long-running tunnels.

The client quietly checks your panel for a newer release and tells you when one exists. To act on it:

threadway update --check     # just report what's available
threadway update             # download + replace (prebuilt binaries only)

Running from source? update won't overwrite your checkout, update via git pull or your package manager instead.

Print a completion script and source it:

source <(threadway completion bash)     # bash, add to ~/.bashrc
source <(threadway completion zsh)      # zsh , add to ~/.zshrc
threadway completion fish > ~/.config/fish/completions/threadway.fish

It's a local web UI that shows every HTTP request and response flowing through your tunnel: full headers, bodies, and timing, so you can debug webhooks and APIs without extra tooling. Turn it on with --inspect:

threadway http 3000 --inspect          # opens on 127.0.0.1:4040
threadway http 3000 --inspect 4500     # custom port

Then browse to http://127.0.0.1:4040.

Yes, open any captured request in the inspector and hit Replay to send it to your local app again. Great for re-triggering a webhook you just received without asking the sender to fire it again.

The inspector binds to 127.0.0.1 only, so it's local to your machine. It's opt-in (off unless you pass --inspect), works for HTTP tunnels, and only reads copies of the traffic. It never alters what your app sends or receives.

A catcher is a unique public URL that logs whatever hits it. No local app required. It's the Threadway take on RequestBin / webhook.site, useful for confirming a webhook fires or catching an out-of-band callback in a CTF.

threadway webhook create            # new catcher with a random label
threadway webhook list              # your catchers + their URLs
threadway webhook watch my-hook     # stream incoming requests live
threadway webhook watch my-hook --body   # include request bodies
threadway webhook rm my-hook        # delete it

If the operator has enabled the capture servers, yes, the deployment can include delegated DNS and SMTP capture zones (e.g. <label>.dns.example.com and x@<label>.smtp.example.com). Blind DNS lookups and emails sent to those names are recorded, which is exactly what you want for blind SSRF, blind XSS, and exfil checks. Availability depends on the server setup.

On your Account page, verify your email, then switch on two-factor authentication. After that, signing in asks for a 6-digit code emailed to you (valid ~10 minutes, a few tries before it expires). 2FA is per-account and opt-in.

• Recovery codes, a set of five single-use codes you generate and store safely. Any one of them works in place of an emailed 2FA code, or to reset your password if you're locked out. Regenerate them anytime (old ones stop working).
• Recovery email, a second address that also receives password-reset links, so you're not stuck if you lose access to your primary inbox.

Go to Recover your account and choose one of two paths: get a reset link by email, or enter a recovery code to set a new password right away. Reset links go to both your primary and verified recovery email.

Create keys on your Account page; the full value (prefixed twk_) is shown once, so copy it then. A key authenticates the CLI and the tunnel/management endpoints.

• Active sessions are listed on your Account page; revoke any one (or all others) if a device is lost.
• Remember this device keeps you signed in longer on machines you trust.
• Sudo mode asks you to re-enter your password before sensitive changes, then trusts you for a short window, so a walk-away can't flip your security settings.

Too many failed sign-ins in a row temporarily locks the account for a set number of minutes, which blunts password guessing. Wait it out, or use a recovery code / reset link. Operators can also alert you by email when a lockout happens.

A plan (tier) can cap any of:

• How many tunnels and reserved ports you can have, and connections per tunnel.
• Monthly data and tunnel speed (a rate cap in kbit/s).
• Whether you can use subdomains or reserved subdomains, and how many you may keep.
• Which protocols (HTTP / TCP) you may use, and a maximum tunnel lifetime.

Your panel dashboard shows your plan, current limits, and traffic. From the CLI, threadway ps lists your live tunnels with their connection and byte counts. Admins set the tiers; if you need more headroom, ask whoever runs the instance.

Yes. On the Webhooks page, add a notification webhook (Discord, Slack, or a generic JSON endpoint) and/or enable email alerts, then choose to be notified on tunnel up, down, or both. There's a Send test button to confirm it's wired up.

(Note: these tunnel notifications are separate from request catchers, which capture inbound traffic.)

If you've verified an email, you can opt into alerts for sign-ins from a new device, password changes, 2FA changes, recovery-code regeneration, email changes, and account lockouts. They're all off until you turn them on.

From the admin views: manage users and their plans; create and edit tiers; watch and force-close any tunnel (single or all); suspend or ban accounts; and read a full audit log (exportable to CSV/JSON). The dashboard adds traffic analytics and top source IPs.

Add an IP or CIDR to the blocklist (Settings), or block a noisy address in one click from the top-source-IPs view. There's also automatic blocking: repeated failed logins from one IP earn a temporary, time-limited block that stops both panel sign-ins and tunnel connections.

Settings let a super-admin post an announcement banner (MOTD), toggle open registration and self-activation, and flip on maintenance mode. A super-admin can also reveal a user's recovery details when helping them regain access (every reveal is audited).

Build the binaries (there are build.sh / build.ps1 scripts), drop them in the panel's downloads folder, and list them in the release manifest with their version and checksums. The Download page and threadway update pick them up automatically.

The public visitor's leg to the proxy is HTTPS. The hop between the server and your client is plaintext by default; add --tls to encrypt the control channel. For anything sensitive, run TLS at your own app too. This is expected for a CTF/lab tool, but worth knowing.

Passwords are hashed; API keys are stored hashed (only the prefix is kept readable). One-time 2FA codes and recovery codes are encrypted at rest. Use it only against systems you own or are authorized to test.

Run threadway doctor first. It pinpoints whether DNS, the control port, TLS, the panel, or your key is the problem. Common causes: wrong --server, an expired login (--login again), a blocked control port on your network, or you've hit a plan limit.

With on-demand certificates the very first request to a brand-new subdomain waits a couple of seconds while its certificate is issued, then it's instant. Subsequent requests to that subdomain are not affected.

Prebuilt binaries aren't code-signed, so SmartScreen may show a warning. Choose More info → Run anyway, or build the client yourself from source if you'd rather not.

That's intentional. API keys work for tunnels and read-only account info, but sensitive self-service: managing keys, 2FA, recovery, sessions, and your password, needs a browser sign-in. Log in to the panel for those.

Check spam first. Email only works if the operator has configured an SMTP sender, so on a fresh instance it may be off, ask whoever runs the server. You can still use recovery codes to get in.