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

Download the Lab from the tradectl website:

System	Download
Windows (64-bit)	.exe installer
macOS	coming soon
Linux	coming soon

On first run Windows may say "Windows protected your PC", because the installer is not signed yet: click More info, then Run anyway.

The installer has the bot program and the shot strategy inside, so the Lab can create and run bots on your computer by itself. See Getting started.

Bots on a server

The easy way is the install command: in the Lab, open Profile. Under add a server, press Bot server and paste the command into the server's console. It installs the bot, runs it as a service, opens port 9103, links it to your account and gives it your pair key (see Your pair key). See Path B: on a server.

By hand, with the CLI:

curl -fsSL https://tradectl.com/install.sh | sh
tradectl login                       # paste an API key from app.tradectl.com/account

Add a lab block to the bot's config, so a Lab on another machine can reach it:

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

tradectl run my-bot -c config.json --daemon

A bot set up by hand has no pair key, so the Lab lists it as locked. Pair it with tradectl run my-bot --print-pair (paste the line into Add a bot), or use the install command above.

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:

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.

Settings change only over a direct connection. tradectl.com does not send settings to your bot. If the Lab cannot reach the bot, open the port above, or change the settings on the machine the bot runs on.

Your network needs IPv4

The Lab reaches bots over IPv4 only. IPv6-only networks are not supported. Some phone hotspots and mobile carriers sometimes drop IPv4 and keep only IPv6. Websites still load then, but the Lab cannot reach any bot. To fix it, turn Wi-Fi off and on, or turn the phone's mobile data off and on, until IPv4 works again. To check, run ping 1.1.1.1: it must get replies.

In the Lab: sign in and connect

1. Click Profile at the bottom of the left list and sign in with an API key from app.tradectl.com/account (or it picks up the credentials the CLI already saved on this machine).
2. Your server bots appear in the left list, grouped by machine.
3. Click a bot to connect. The Lab opens a secure, pinned connection straight to that bot.

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.

Your pair key

Your account has one pair key. Only your Labs and your servers have it; tradectl.com never gets it. A bot on a server locks its connection details (the key that controls it) with the pair key before it registers. tradectl.com can list the bot, but it cannot read that key. Your Lab opens it with the pair key. When a bot gets a pair key, it makes a new access key, so any key tradectl.com saw before stops working (a server bot that registered before v0.2.6 also does this once on its first start, key or not). Streams opened with the old key are closed; an open Lab moves to the new one by itself within a minute.

• First Lab: open Profile → pair key and press Make a pair key. Add a server needs it.
• Another computer, or a new install: in the old Lab, open Profile → pair key and press Copy key. In the new Lab, paste it under Enter a key from another Lab and press Save. Keep the key secret, like a password.
• Locked bots: a bot that this Lab cannot open shows locked in the left rail. Enter your pair key, or pair that one bot by hand: on its server run tradectl run <bot> --print-pair and paste the line into Add a bot.
• A server set up before v0.2.6, or without the key: in the Lab, press Add a server and run the new command on that server again. It keeps the bot and adds the key; the running bot picks it up within a minute, with no restart.

Bots on the same computer as the Lab need no pair key: the Lab reads their connection from the bot's folder.

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.
• The platform cannot read your bot's access key. A bot locks its connection details with your pair key before it registers. The platform stores them, but cannot read them, and it cannot change the address the Lab dials: a bot checks an address before it uses it. The server command runs the installer from GitHub, checked by its hash, not from tradectl.com.
• One exception, until strategy files are signed. tradectl install downloads strategy files from tradectl.com, and they run on your machine. Someone who broke into tradectl.com could change them, and a changed file could read your pair key and so reach all your bots. The server command checks shot against a hash on GitHub; later installs and updates are not checked yet.
• Easy revocation. Rotate a bot's credentials anytime with tradectl run <bot> --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 listed under My bots. Press the refresh button above the bot list.
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.
Bot shows locked	This Lab has no pair key, or another one. Enter your pair key in Profile → pair key. If the bot's server never got the key, run the Add a server command there again.
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.
No bot connects, but websites load	Your network has no working IPv4 (some phone hotspots drop it). The Lab needs IPv4: see Your network needs IPv4.
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.