🐺 NOCTURNA Trading System

A trading robot that refuses to fool you. Connect a free Alpaca paper account → it trades a calm stocks-and-bonds portfolio behind hard safety limits → you watch it from your phone, and no "clever" strategy gets a cent until it survives a gauntlet of tests built to catch lucky backtests.

[!WARNING] Paper trading only, on purpose. Live trading is switched off in the code: the app won't start unless TRADING_MODE=PAPER and it points at Alpaca's paper API. No strategy here has passed out-of-sample validation, so none should be trusted with real money.

---

🤔 What is this?

Most trading bots you find online come with a gorgeous backtest: a line that goes up and to the right forever. Then they meet the real market. 📉 The backtest was luck, tuned until it looked good.

NOCTURNA is built the other way round. It's a self-hosted robot for one person that trades US ETFs through Alpaca, and it's paranoid by design:

• 🛡️ Safety first. Every order, from the robot or from you, passes one risk gate. If the account falls 10% below its peak, trading halts and every position is closed.
• 🧪 No strategy on faith. A new idea must survive walk-forward testing, a deflated Sharpe ratio, an overfitting test and triple trading costs before it may trade. So far none has, so the robot sticks to a plain 60/40 portfolio.
• 💵 Idle cash works. Whatever the safety rules leave unused sits in T-bills (BIL), not in cash earning nothing.
• 🎛️ You choose what trades. Pick strategies and the share of the account each one gets, tune the risk limits inside hard bounds, and backtest or validate any mix in the dashboard's strategy lab before it trades. A strategy that failed validation says so, and asks you to confirm that you read why.
• 📱 It lives in your pocket. A phone-first dashboard in a night theme, with the wolf, and a Telegram bot: check positions, start, stop, or hit the emergency stop from anywhere.
• 🏠 It runs at home, 24/7. One setup script turns an Ubuntu machine into the robot's home: Docker, daily backups, alerts, and a dead man's switch that tells you if it ever goes quiet.
• 🔒 Paper only. Real-money trading is disabled in the code itself.

No finance degree required. If you can copy-paste a few commands and use a phone, you can run it.

---

🖼️ Gallery

---

📊 The honest scoreboard

Every idea below follows its published rules (the six newest had theirs written down before their first backtest) and went through the same tests. The verdicts come from the years the tests held back, January 2020 to October 2026, which a strategy never sees while it is being chosen:

Idea	Verdict	In plain English
🥧 60/40 stocks and bonds (benchmark)	✅ Trades on paper, as the yardstick	6.3% a year, worst drop −12%. Tested back to 1974 on free data: 8.1% a year, worst drop −15%, five kill-switch stops in 52 years
🔁 Front-running pension rebalancing (rebalancing)	❌ Rejected	The edge shows up between closes and vanishes by the next morning's open. It would also churn the portfolio about 43 times a year
📈 Trend following on 12 ETFs (tsmom)	❌ Rejected	Too weak out of sample
🪙 Crypto breakouts (crypto-trend)	❌ Rejected	Too weak out of sample (2024 to 2026: Alpaca's crypto data starts in 2021)
🧩 The three above, combined (lineup)	❌ Rejected	Didn't beat the plain 60/40
📅 Month-end payment cycle (month-end)	❌ Rejected	21.4% in almost seven years, against T-bills' 20.3%
🌊 Trend filter on the 60/40 (trend-filter)	❌ Rejected	A tie with the 60/40 since 2017, a little behind it since 1974. It did hit the kill switch only twice in 52 years, against five times
🐢 Low-volatility funds instead of SPY (low-vol)	❌ Rejected	3.6% a year, against the 60/40's 6.3%
🛢️ Commodities in the 60/40 (commodities)	❌ Rejected	About level with the 60/40 since 2020 (Sharpe 0.56 against 0.53), with signs of luck in the choice of weight. Since 2001 it fell deeper than the plain 60/40
🌍 International stocks in the 60/40 (international)	❌ Rejected	5.4% a year since 2020, against the 60/40's 6.3%, and behind it since 1990 too
🥇 Gold in the 60/40 (gold)	❌ Rejected	Better since 2020 (7.8% a year, worst drop −11%) because gold quadrupled. But from 1975 to 2000, when gold lost almost two thirds, it earned less per unit of risk than the plain 60/40, and its best gold weight looks overfit

The 60/40 row is the live portfolio, held at 60/40. The rejected ideas were compared with the 60/40 validated the same way they were, with its stock weight (40–80%) re-chosen each year; that earned about the same, 6.3% a year since 2020 and 8.2% since 1974.

Ten rejections out of ten isn't the robot failing. It's the robot doing its job. 🐺 The numbers, sources and reasoning are in the strategy shortlist and the roadmap.

---

🚀 Get started in 3 steps

1. Get a free paper account

Sign up at Alpaca and create paper trading API keys. Play money only: NOCTURNA won't start with anything else.

2. Set it up on a home server (recommended)

On an Ubuntu machine:

git clone https://github.com/Yog-Sotho/Nocturna-Trading-System.git
cd Nocturna-Trading-System
sudo ./setup.sh --check    # only looks: what's installed, and what it would change
sudo ./setup.sh            # lists the changes first, then asks before making them

The setup installs what's missing (Docker, Compose, Tailscale) and puts the dashboard on a private Tailscale address. It writes your .env, asking only for what only you know, like your Alpaca keys. Then it starts everything, creates your dashboard login and sends a test alert. It never adds anyone to the docker group, and never touches what Tailscale already serves.

The step-by-step guide, with every setting explained, is HOME_SERVER.md.

3. Start the robot

Open the dashboard on your phone → Start engine → confirm. Or send /start_engine to your Telegram bot, then the /confirm code it replies with.

From then on it wakes up each time a new daily bar is final, works out what to hold, and trades at the next opening auction.

Just want to look around first? 👀

Try the real dashboard on a simulated robot with made-up prices. No account, no keys:

git clone https://github.com/Yog-Sotho/Nocturna-Trading-System.git
cd Nocturna-Trading-System
python3 -m venv .venv && source .venv/bin/activate    # Python 3.13 or newer
pip install -r requirements.txt
python tools/dashboard/serve_sim.py . /tmp/dashboard.db 5055

Open http://127.0.0.1:5055 and sign in as ops / Harness-Passw0rd!. Start the engine and one simulated trading day passes every three seconds. The strategy lab runs on the same made-up prices.

---

🧰 "I want to…" cheat sheet

I want to…	On the dashboard	In Telegram
see how it's doing	the Account card	/status
see what it holds	Positions	/positions
start or stop the robot	Start engine / Stop engine	/start_engine / /stop_engine
stop trading now, keep my positions	Emergency stop → Keep the positions	/halt
stop trading now and sell everything	Emergency stop → Close every position too	/flatten
carry on after a halt	Resume after halt	/resume
change which strategies trade, and how much each gets	Strategies → Save the mix → Restart now
change a risk limit	Risk → Save the limits
backtest a mix, or validate a strategy	Lab → Run
choose which alerts I get, and where	Alerts
make sure my alerts arrive	Alerts → Send a test alert
change my name, the theme or the accent colour	You

Every Telegram command that changes something asks for a /confirm <code> first, so a stray tap does nothing.

On the server (put sudo docker compose exec api in front of each):

I want to…	Run this
check paper trading against a backtest of the same days	flask --app src.main soak report
test a strategy idea on Alpaca data	flask --app src.main validate benchmark --start 2017-01-01
test it on free data back to 1970	flask --app src.main validate benchmark --data history --start 1971-01-01 --end 2026-08-31
make sure my alerts arrive	flask --app src.main send-test-alert

And on the machine itself, sudo ./setup.sh --check reports what's installed and configured, without changing anything.

---

🛡️ The safety limits

These are the defaults, all as fractions of the account's value. You can change them in .env, and they apply the same way in backtests and on paper:

Limit	Default
Kill switch: halt and close every position	10% below the account's peak
Shrink exposure gradually as losses grow (down to 25% at the kill switch)	from 5% below the peak
Daily loss limit: no new risk for the rest of the day	3%
Volatility target (scales down only, never borrows)	8% a year
Largest position / all crypto together / everything together	60% / 15% / 100%
Largest single order (fat-finger guard)	60%
Limit prices more than this far from the last close are refused	5%
The same order twice within 5 minutes	refused
Orders / turnover per day	50 / 2× the account
Market data older than / a one-bar jump bigger than	stocks 5 days / 25%, crypto 2 days / 50%
Positions are adjusted only when this far from target	2%
Idle cash	in T-bills (BIL), less a 0.5% buffer

Orders that only shrink a position are always allowed, so the book can always be reduced. A halt is saved in the database, so it survives a restart. The fine print is in the technical reference.

---

🧪 How a strategy earns the right to trade

Run flask validate on any idea, or press Run in the dashboard's Lab, and the robot puts it through this gauntlet, with the same engine, costs and safety limits as paper trading:

Test	What it catches	To pass
Walk-forward	Ideas that only work on the data they were tuned on	Return per unit of risk above T-bills (Sharpe) of at least 1.0, on years held back
Deflated Sharpe	A "best result" that is just the luckiest of many tries	At least 0.95
Overfitting test	Settings that look best in-sample and flop out of sample	At most a 20% chance
Triple costs	An edge that trading costs would eat	Still beats T-bills
Neighbours	A lucky spot in the settings	Nearby settings at least half as good
Worst drop	Risk beyond the safety limits	No more than 12%
Paper soak	A backtest the real market doesn't confirm	60 trading days tracking the backtest

It writes a full report and ends with its verdict: rejected, naming the tests it failed, or eligible for paper trading. The dashboard shows each strategy's verdict next to it, and you can still paper-trade a rejected one once you confirm you read why. How each test works is in the technical reference.

---

🔐 Your money and your keys stay yours

Everything runs on your own machine. Your Alpaca keys live in your .env and go only to Alpaca. With the home-server setup, the dashboard is reachable only through your private Tailscale network, and it has one operator account: yours, with public sign-ups switched off. The free long-history data (Kenneth French's data library and FRED) is downloaded only when you ask for it.

---

🗺️ What's been built, what's coming

Already available:

• ✅ One trading core: the same code in backtests and on paper
• ✅ Risk gate, kill switch, daily loss limit, volatility target and the drawdown ladder
• ✅ Validation gauntlet: walk-forward, deflated Sharpe, overfitting tests, cost stress
• ✅ Long-history tests on free data back to 1970
• ✅ Idle cash in T-bills
• ✅ Phone-first dashboard in a night theme (or a day one), with five accent colours
• ✅ A strategy mix you choose on the dashboard, with risk limits inside hard bounds
• ✅ A strategy lab: backtests and validations from the dashboard, with their reports
• ✅ Telegram commands with confirmation codes
• ✅ Alerts (Telegram, ntfy, webhook) you choose by kind, and a dead man's switch
• ✅ Home-server setup with Docker Compose, daily backups and an optional HTTPS proxy
• ✅ Versioned REST API with an OpenAPI 3.1 document
• ✅ About 1,000 automated tests, strict typing on the trading core, mutation testing of the risk code

Coming next:

• ⏳ A 60-day paper soak on a real paper account, measured against its backtest
• ⏳ Only after that, and only for a strategy that passes every test: a staged move to real money

---

🤓 For the nerds

Read the guides as a website at yog-sotho.github.io/Nocturna-Trading-System, or right here:

Guide	What you'll find
Technical reference	Every component, the API, every setting, development and CI
Architecture	How the engine, risk gate, sizing and validation fit together
Home server	Setting up the machine, step by step
Runbook	Alerts, upgrades, incidents, backups and restores
Roadmap	The plan, the decisions and the promotion gates
Strategy shortlist	Every idea tested, its sources, its rules and its result

---

🤝 Contributing

Contributions welcome! Fork the repo, make your change, and run the checks before opening a pull request:

pip install --require-hashes -r requirements-dev.txt
pytest src/tests && ruff check src/ tools/ setup/ && mypy

Found a bug? Open an issue with what you ran and the full error message.

---

📜 License

MIT: free to use, change and share. See LICENSE.

⚠️ Disclaimer

This software is provided as-is, without warranty. Trading involves a substantial risk of loss. Nothing in this repository is investment advice.

---

Made with ❤️, caffeine and a healthy distrust of backtests.

If NOCTURNA saved you from a strategy that only worked on paper, a ⭐ on GitHub means the world. Yog-Sotho