tradectl Lab

tradectl Lab is a native desktop app for watching your live bots — a streaming chart, fills, positions, trades, and the bot's own logs, all in one window — and for running backtests and sweeps against your local data.

The headline feature: sign in once, and every bot you run shows up in the Lab automatically.

How it fits together

Your bot, the platform, and the Lab play three distinct roles:

• The bot runs on your server and, on startup, tells the platform "here's how to reach me."
• The platform is a phonebook — it remembers which bots belong to you so the Lab can list them. It never sees your market data or trades flowing live.
• The Lab signs in, asks the platform for your bot list, and then connects straight to each bot over a secure, pinned connection. Live data goes bot → Lab directly, never through the platform.

Download & install

tradectl Lab is a desktop app you download from the tradectl website. Grab the build for your operating system:

Platform	Download
Windows	.exe installer
macOS	.dmg (Apple Silicon or Intel)
Linux	.AppImage

On the server: link your account and run

1. Install the CLI and sign in:

curl -sSL https://tradectl.com/install.sh | sh
tradectl login                       # paste your API key from tradectl.com/account/api-keys

2. Enable the Lab API in the config, then run the bot:

Add a lab block to your bot config JSON — this is the single place the Lab-facing API is configured (there are no CLI flags for it):

"lab": { "enable": true, "bind": "0.0.0.0" }

tradectl run config.json --daemon

That's it on the server side. No connection strings to copy.

Your public IP is filled in for you

When you bind to 0.0.0.0, the platform sees the request come from your server's public IP and records that as the bot's address — so the Lab knows where to dial. Behind NAT (e.g. a home server), the platform can't guess your routable address; set "publicHost": "<ip-or-dns>" in the config lab block and forward the port.

Open the firewall

The Lab connects inbound to the bot, so your server's firewall must allow the bot's port. This is the one manual step:

ufw allow 9103/tcp                   # or open the range 9103-9120 if you run several bots

The bot keeps trading regardless — reachability only affects whether the Lab can connect.

In the Lab: sign in and connect

1. Open the Profile tab and sign in (or it picks up the credentials the CLI already saved on this machine).
2. Open the Bots tab. Under My bots, your servers appear grouped by machine.
3. Click Connect. The Lab opens a secure, pinned connection straight to that bot.

Each bot shows when it was last seen (its most recent check-in). The platform doesn't probe whether your port is open — click Connect to confirm reachability; the indicator goes green once the Lab is connected.

Connect Telegram

Get trade alerts and control your bots from Telegram — no BotFather token to create, no chat id to copy anywhere.

1. Open Profile in the Lab.
2. Click Connect Telegram. It opens @tradectlbot — tap Start.
3. The card flips to Connected as @you on its own.

On another device? The card also shows a code (e.g. /link 7KQ2-M9XF) — send that to the bot from wherever Telegram is open, and you're connected the same way.

See the Telegram guide for the full command reference and how it behaves once you're running more than one bot.

Is it secure?

Yes — and the platform being only a phonebook.

• Live data never touches the platform. Once the Lab has a bot's address, it connects directly to the bot. The platform sees only "this bot belongs to this account, at this address" — never your prices, fills, or positions.
• Pinned certificate. Each bot presents its own self-signed certificate, and the Lab trusts only that one certificate.
• Stored safely. When a bot registers, the platform stores its connection details encrypted.
• Easy revocation. Rotate a bot's credentials anytime with tradectl run config.json --rotate-pair, then restart the bot. Every previous connection string stops working instantly, and the new one re-registers automatically.

Troubleshooting

Symptom	Cause / fix
Bot doesn't appear under My bots	Make sure the server ran tradectl login and the config has "lab": { "enable": true, "bind": "0.0.0.0" }. A loopback-only bot is never published. Hit the refresh button in the Bots tab.
Bot listed but won't connect	The port is likely closed on the server — open it: ufw allow <PORT>/tcp (or your cloud security group). Behind NAT, set "lab": { "publicHost": "<ip-or-dns>" } and forward the port.
Bot's last seen is stale	The bot may be stopped, or its address changed. Restart it; it re-registers on startup.
unauthorized — token rejected on connect	The bot's credentials were rotated. In My bots, refresh and reconnect; for a pasted blob, re-paste from --print-pair.
certificate fingerprint mismatch	The certificate was rotated, or you're connecting to a different bot. Refresh / re-paste the current connection string.
Live chart stuck on Reconnecting	The bot is down, the firewall is blocking the port, or (behind NAT) the address isn't routable — set "lab": { "publicHost": "<ip-or-dns>" } in the config and forward the port.
Live chart stays empty	The bot isn't streaming yet — confirm it's running and receiving market data.
Connected, but Trades is empty	Connection is fine — the bot just has no closed trades yet.
Pasted blob is rejected	The string is truncated. Re-copy the whole tctl-pair-1:… line.