trqsh
Guides4 min read

Troubleshooting

Check the path in order: local service → agent configuration → sign-in → edge connection → public request. A working website does not prove that every part of the tunnel path works.

On this page

1 Check the local service#

Test the exact target address on the computer running the agent:

curl -i http://127.0.0.1:3000/

If it fails locally, fix the app/port first. Check whether the target expects HTTP, HTTPS, TCP or UDP. An HTTP tunnel's upstream must speak HTTP in the current implementation.

If the agent runs inside a container, localhost means that container. Use its network's service address or an appropriate host gateway.

2 Check the selected configuration#

Inside the console:

/config
/status
/whoami
/ls

Confirm that the API origin and edge belong to the same deployment. Hosted defaults are https://trqsh.uz and trqsh.uz:4443; the persistent local stack uses http://localhost:8081 and 127.0.0.1:4443.

The loader's normal file is ~/.trqsh/trqsh.yml, not ~/.trqsh-uz/trqsh.yml.

If you edited config or environment while the daemon was running, enter /down and relaunch. /config displays launcher settings; an old daemon may still have its earlier settings until restarted.

3 Fix authentication#

If /whoami fails, check the Control API URL and API key. Run /login again, or create a replacement key in the correct dashboard.

For device approval, use the full printed URL and complete it within 10 minutes. An expired code must be replaced.

A local development account/key is independent of the hosted account/key. If logout appears ineffective after a restart, check whether TRQSH_API_KEY is still set.

4 Check edge connectivity#

The agent's edge transport normally uses port 4443, separate from website HTTPS on 443.

On Windows:

Test-NetConnection 127.0.0.1 -Port 4443

Replace the host with your configured edge. This tests TCP reachability, not QUIC/UDP.

For networks that block UDP, restart using TCP transport:

trqsh --transport tcp http 3000

First stop an existing daemon with /down so the changed option takes effect. With transport: auto, QUIC is attempted with TCP fallback. Forcing QUIC removes that fallback.

A public HTTP reverse tunnel for the website does not automatically publish the agent's custom transport.

Public URL returns an error#

Symptom Likely cause / action
502 / local service unreachable App stopped, wrong port/address, TLS-only upstream or container-localhost mismatch.
404 before reaching your app No active bind for that hostname, wrong Host header or request routed to the wrong edge.
App says invalid Host Use host_header in YAML/local API or adjust the framework's allowed hosts.
Basic Auth prompt/rejection Check basic_auth credentials on that saved tunnel.
Certificate warning on *.lvh.me Local development uses self-signed certificates.
Certificate warning on your public domain Check DNS, verified ownership and production ACME/certificate configuration.

Test a route your app actually has. A 404 generated by your application can mean the tunnel is working correctly.

Named tunnel cannot start#

Reserve a requested subdomain with the same account before binding. An arbitrary --subdomain does not create a reservation.

Verify a custom domain's exact TXT token, then use custom_domain in a saved definition or local API request. The current console's --domain argument is not applied.

An already-active bind can own the hostname. Check /ls, stop the old tunnel and retry.

CLI option seems ignored#

Place root options before the initial command: trqsh --transport tcp http 3000.

The console start parser accepts --subdomain/-s and --remote-port. Use configuration or the local API for Basic Auth, custom domain and Host-header fields.

The CLI requires an interactive terminal. A pipe, redirect or background CI launch of trqsh http is not a headless workflow. Use Webhooks & CI.

Local port already occupied#

The default agent ports are 4041 (control) and 4040 (inspector). Another trqsh daemon or desktop instance may already use them.

Before changing anything, identify the owner. On Windows:

Get-NetTCPConnection -LocalPort 4040,4041 -State Listen |
  Select-Object LocalAddress,LocalPort,OwningProcess

Exit the interface that owns the agent cleanly, or choose distinct loopback addresses for your job. Do not stop unrelated processes.

Inspector is empty#

Send a normal HTTP request and wait for it to complete. Raw TCP/UDP and WebSocket frames do not appear as HTTP exchanges.

Verify the inspector address and the local agent process. The buffer is in memory, holds 256 captures and is reset when the agent exits. The dashboard cloud-inspector page is not yet connected to a capture archive.

Docker stack checks#

Use the same project/files as startup:

docker compose -p trqsh-local -f deploy/docker-compose.dev.yml -f deploy/docker-compose.local.yml --profile web ps
docker compose -p trqsh-local -f deploy/docker-compose.dev.yml -f deploy/docker-compose.local.yml --profile web logs --tail 100 api edge site

Check http://localhost:8081/healthz and http://localhost:9090/healthz. The migration container exiting with code 0 is normal.

Port conflicts must be solved in this project's overlay. Frontend origin changes require rebuilding the affected frontend. Preserve database volumes; do not use down -v as a routine troubleshooting step.

Collect useful diagnostics#

Include the CLI version, OS, selected transport, affected protocol, sanitized target/public hostname, error code and approximate time. For a standalone agent, logs are beside the default/environment-selected config in daemon.log.

Remove API keys, local tokens, Basic Auth passwords, cookies and private payloads before sharing logs. Stable edge codes have specific fixes in the Error reference.