Mursalin Kabir

How to connect an AI agent to TraderBuddy over MCP

Sat, 17 Oct 2026 16:10:10 GMT

TraderBuddy runs an MCP server, so Claude Code, Cursor and other AI agents can look up a stock, read your alerts and portfolios, and manage alerts, your watchlist, chart drawings, saved scanners, the daily digest and your portfolio transactions without opening the browser. It takes about two minutes to connect. It tracks and alerts; it never trades, and nothing an agent does can place an order.

What you can ask

Once it is connected, you talk to your agent in plain words and it calls TraderBuddy's tools for you:

"Give me the full picture on NVDA." Price and 1d to 1y change, the 52-week range, distance from the 50- and 200-day averages, RSI, valuation, analyst ratings, and whether you already watch, hold or have an alert on it.
"Alert me if SPY closes below its 200-day average."
"Which of my alerts have triggered this month, and why?"
"Scan the S&P 500 for stocks with RSI under 30 that are still above their 200-day average, and save it as 'Dip buys'."
"Draw a support line at 187.50 on AAPL and alert me on it."
"What are the macro readings that say risk-off right now?"

How it works

The endpoint is https://trader.smkabir.com/api/mcp/, and it signs you in with a personal access token that you create yourself. There is no OAuth sign-in for agents: Zitadel, the identity provider, does not support the dynamic client registration agents need, so a token is how an agent proves it is acting for you.

(Diagram: view it on the website.)

The MCP server is not a separate service. It lives inside the API, and every tool calls the same REST routes the browser uses, carrying your token. So an agent gets exactly what you get in the browser: the same validation, the same approval check, the same per-user privacy and the same rate limits. Nothing is reimplemented, so nothing can drift or be bypassed.

Step 1: create a token

In TraderBuddy, open Settings → Agent access → New token. Give it a name you will recognise ("Claude Code on laptop"), choose what it may do, and pick an expiry: 30 days, 90 days or a year. There is no "never".

Scope	The agent can
Read only	Look at everything listed below. Change nothing.
Read and write	Also create, change, renew and delete alerts; manage the watchlist; draw and delete chart lines; save, change and delete scanners; turn the digest and opening movers on or off; create a portfolio and add or correct its transactions.

The token starts with tb_pat_ and is shown once. TraderBuddy keeps only a hash of it, so if you lose it, revoke it and make another. Treat it like a password: anyone holding it can act as you within its scope. Start with read-only, and make a read-and-write token only when you want the agent to change things.

Step 2: give it to your agent

Claude Code takes one command:

claude mcp add --transport http traderbuddy https://trader.smkabir.com/api/mcp/ \
  --header "Authorization: Bearer tb_pat_…"

Cursor reads ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "traderbuddy": {
      "url": "https://trader.smkabir.com/api/mcp/",
      "headers": { "Authorization": "Bearer tb_pat_…" }
    }
  }
}

Any other client that supports a remote (HTTP) MCP server with a custom header works the same way: the URL above, and the header Authorization: Bearer tb_pat_…. Where that goes differs between clients and versions, so follow your client's own documentation. The URL works with or without the trailing slash.

A project's .cursor/mcp.json is easy to commit by accident. Put the token in your user-level config, or make sure the project file is ignored.

Step 3: check it is connected

$ claude mcp list
traderbuddy: https://trader.smkabir.com/api/mcp/ (HTTP) - ✔ Connected

Then ask the agent "Who am I in TraderBuddy?". It calls whoami and answers with your account and whether it is approved. A pending account's token is refused until an admin approves it.

The tools

Read tools, any token:

Tool	Does
`get_stock_details`	The one to start with: price, changes, 52-week range, trend, valuation, analysts, and what you already have on that symbol.
`search_symbols`	Find a ticker by name. Says whether it is an ETF or fund.
`get_bars`, `get_indicator`	Candles and server-computed indicators: the same numbers the chart shows.
`get_market_clock`, `get_news`	Whether the market is open; recent headlines.
`list_macro`, `get_macro_series`	Treasury yields, Fed funds, CPI, unemployment, VIX, CAPE, each with whether a rise is good or bad.
`list_watchlist`, `list_alerts`, `get_alert_events`	Your watchlist, your alerts, and each time an alert fired and why.
`list_portfolios`, `get_portfolio`, `get_portfolio_transactions`, `get_portfolio_history`	Value, P&L, positions, allocation and the ledger.
`get_financials`	Financial health from the latest 10-K or 10-Q: a 0–100 score, five pillars, the Piotroski and Altman checks, and optionally five years of statements.
`get_scanner_fields`, `list_scanners`, `run_scanner`, `scan`	List what a scan can filter on, run a saved or built-in scanner, or try an unsaved one. Results are as of the last close.
`list_drawings`, `get_digest_settings`, `list_notification_channels`, `whoami`	Chart drawings, digest settings, where alerts are delivered (never the credentials), and your account.

Write tools, read-and-write token:

Tool	Does
`create_price_alert`, `create_condition_alert`	Alert on a price level, or on a moving-average cross, golden or death cross, daily % move, new high or low, volume spike or RSI level.
`update_alert`, `renew_alerts`, `delete_alerts`	Change an alert, extend it by 90 days, or remove it.
`add_to_watchlist`, `remove_from_watchlist`, `reorder_watchlist`	Manage the watchlist.
`draw_horizontal_line`, `draw_trendline`, `delete_drawing`	Draw on a chart, optionally with an alert on the line.
`create_scanner`, `update_scanner`, `delete_scanner`	Save a scan; `notify` sends its matches to your channels after each close.
`create_portfolio`, `add_portfolio_transactions`, `update_portfolio_transaction`	Record holdings: up to 200 transactions at once, all stored or none. The whole ledger is replayed, so an impossible sell is refused and the reply names the row.
`set_digest_settings`	Turn the daily digest and opening movers on or off.

Tools that delete are marked as destructive, so a client can ask you before running them.

What an agent can never do

These are not settings. They are walls in the API, enforced no matter which client or token is used:

Trade. There is no order entry anywhere in TraderBuddy.
Touch notification credentials. It can see that a Slack, Telegram or webhook channel exists and whether it works, but cannot add, change, remove or test one. Otherwise bot tokens would end up in the agent's conversation history.
Use the admin area, even if your account is an admin. A token carries no roles.
Create, list or revoke tokens. Only a signed-in browser can, so a leaked read-only token cannot upgrade itself.
Delete from a portfolio. It can add and correct transactions, but not delete a transaction or a portfolio, rename one, or import a file. Anything it adds wrongly, you remove in the browser.

Anything not on the allowlist is refused by default, and a test fails the build if a new route is added without a decision about whether tokens may reach it.

Things worth knowing

Alerts are not live. They are checked once per trading day, after the US close. "Alert me when it crosses 200" means "tell me after the close on the day it did". The agent is told this and should not promise instant notification.
Money is a string. Prices and quantities come back as exact decimals in strings ("187.500000"), never floats.
ETFs yes; mutual funds and index levels no. SPY, QQQ and VOO work. VFIAX and the S&P 500 index itself are not in the data, so alert on the tracking ETF.
Rate limit. 120 requests a minute per token. get_stock_details makes about a dozen requests by itself.
No duplicate detection for transactions. Ask the agent to read the portfolio's transactions before it adds a statement, and add a given statement once.

When something goes wrong

You see	Cause
401 "Missing or malformed access token"	No `Authorization: Bearer tb_pat_…` header reached the server.
401 "invalid, expired or revoked"	Exactly that. The three look the same on purpose. Make a new token.
403 "account has not been approved"	An admin has not approved your account yet.
"This access token is read-only"	The call needs a read-and-write token.
429 "Rate limited"	Over 120 requests a minute. The message says how long to wait.
Tools return nothing for a symbol	Check the ticker with `search_symbols`.

To revoke a token, open Settings → Agent access → Revoke. It takes effect on the next request.

For what the rest of TraderBuddy does, see Everything TraderBuddy does.

Written for TraderBuddy 0.18.0, 18 October 2026.

How smkabir.com stays up: releases, pointers and a failover that is still on paper

Mon, 12 Oct 2026 09:00:00 GMT

This site is static files served by two small nginx pods in a homelab. That is a deliberately boring design, and it makes the interesting question easy to state: what keeps the site up when something breaks? This post is the honest answer, including the part that does not exist yet.

Built and running: content that lives outside the container image, release and pointer handling in object storage, pods that follow the pointer, verified publishing, rollback, and two replicas on different hosts.

Designed, not built: the failover Worker that would serve a copy of the site from object storage when the whole homelab is unreachable. Until it exists, a power cut or an internet outage takes the site down. Everything below says which side of that line it is on.

The shape of it

(Diagram: view it on the website.)

Nothing a visitor requests ever touches a database or a CMS. Pages are files. That is why the failure modes are few and the recovery is mostly "serve the previous files".

The content is not in the image

The container image holds nginx and a small sync program, and no site content at all. The site itself is a release: a folder in an object-storage bucket named after the build, such as releases/c280dba-38211385696/. Two small text files point into it:

LATEST names the release the pods should serve.
VERIFIED names the release that was actually seen serving correctly on the real site.

A new post is therefore not a deployment. There is no commit to the cluster repository, no image build and no rollout. A publish uploads a folder and moves a pointer.

How a pod follows the pointer

Each pod runs a sidecar that does the same small loop every 60 seconds:

Read LATEST. If it is empty, unreadable or not a plain id, do nothing and keep serving.
If it is already the live release, stop.
Download the release next to the live one, never over it.
Refuse it unless index.html exists and version.json says the same id as the folder.
Turn the release's redirect list into an nginx map using a strict character allow-list, so a bad entry can never inject configuration.
Swap the current symlink in one atomic rename, ask nginx to reload, and delete everything but the live release and the previous one.

If any step fails, the previous release keeps serving. A visitor never sees a half-written site, and R2 being down means "keep what you have".

A release, from push to live

The publish job is one pipeline, and its order is the point:

Build and gate. Formatting, type checks, tests, a privacy scan (no GPS in images, no addresses or phone numbers), the build, and checks on the output: no inline scripts, correct language on every page, no drafts anywhere, every link resolves.
Upload to releases/<id>/ and re-verify the upload. A release is immutable: the same id with different content is refused, and re-running is a safe no-op.
Move LATEST. The pods start syncing within a minute.
Wait until the public site reports the new id. This polls the real URL for up to ten minutes.
Move VERIFIED, purge Cloudflare's cache and prune releases beyond the last twenty.

If step 4 never succeeds, the run fails loudly, VERIFIED does not move, and the live site is untouched.

Why there are two pointers

LATEST says what to serve. VERIFIED says what is known to work. They are separate because the thing you want to fall back to must never be a release nobody has looked at. A bad build can become LATEST for a minute; it cannot become VERIFIED, because VERIFIED only moves after the live site has reported that exact id. Any fallback reads VERIFIED, so a fallback is never a gamble.

What happens when something fails

What fails	What happens	State
A bad or half-uploaded release	The sidecar rejects it; the previous release keeps serving. `LATEST` only moves after the upload is verified.	Built, tested
R2 is unreachable	Running pods keep serving what they have. A pod that has to start from scratch stays unready until it can fetch, so it takes no traffic.	Built, tested
One pod dies	The other serves. Two replicas on different hosts, at least one always available, and a rolling update never drops below that.	Built, running
A node is lost	Pods are rescheduled. Spread is soft on purpose, so losing one host cannot leave a replica stuck pending.	Built
The CI check cannot reach the site	The job fails, `VERIFIED` does not move, the live site is untouched.	Built, seen in production
The whole homelab is unreachable (power, ISP)	The site is down. Publishing also stops.	Not covered yet
Cloudflare itself has an outage	The site is unreachable. Nothing here helps.	Out of scope

The failover that is not built yet

When the tunnel has no healthy connectors, Cloudflare answers with an error page, and its edge cache only helps on points of presence that happen to be warm. The design is a small Worker in front of the site:

(Diagram: view it on the website.)

Reads only. Anything other than GET or HEAD goes straight to the origin; the Worker never invents a write.
The mirror is VERIFIED. It is the same bucket the pods read, so there is no second copy to keep in sync, and it never serves an unverified build.
Same headers. The security headers come from one source file that renders both the nginx configuration and the Worker, so a mirrored response carries the same policy as an origin one.
Visible. Mirror responses carry X-Served-From: mirror, and an external uptime probe is meant to alert when it appears.
What still fails when the homelab is down: publishing and previews. Reading, the resume, search and the feeds keep working, because they are files.
The drill: scale the deployment to zero through the cluster repository (Argo CD would undo a manual change within seconds), check the key pages and the header, then revert the commit.

It is on paper because the site only went live today and the failover is the next unit of work, not because it is hard. The release layout was chosen so that it is a small Worker and not a second system.

Rolling back

Content: a manual workflow takes a build id, checks the release exists and is consistent, and rewrites LATEST and VERIFIED to it. The pods follow within a minute.
Code (the image): a tag is never moved. A fix is the next patch, and a rollback is reverting the commit that bumped the tag in the cluster repository.

What has been proven, and what has not

Proven in production in the last day:

Object storage: uploads, pointer moves, pruning, and pods reading with a read-only token. The token that can write is a different token, held only by CI.
GitHub Actions: the content pipeline and the image release, including a vulnerability scan that stopped a release for a HIGH finding in a library the image did not need.
The cluster path: Argo CD sync, two ready pods on different hosts, the gateway route and the tunnel to the apex.
Tests that exist: 61 image checks (sidecar, nginx under the cluster's restrictions, redirects), 35 release-script checks, an end-to-end run of the real site through nginx, and unit tests.

Not proven: the failover Worker (it does not exist), a real power cut, and a sustained outage of the object store.

The wall CI hit on day one

The check in step 4 above failed for ten minutes with "last saw nothing". The site was serving the right release; the CI runner was being handed Cloudflare's "Just a moment…" challenge page, because Bot Fight Mode treats a datacenter address as a bot. The fix was one switch. The more useful change was to the script: it now reports the HTTP status and the first bytes of what it received, instead of collapsing a challenge page, a 404 and a dead tunnel into the same word. A failure message that cannot distinguish its causes is a bug in the failure message.

What I would still fix

Build the failover Worker. It is the one gap in the table above.
Alert from outside the house. In-cluster monitoring goes dark with the cluster; a probe on a Worker cron does not.
Move content authoring into the CMS and publish through it, so that the pipeline above is triggered by a publish rather than by a commit.
Cache the HTML at the edge. Today every page view reaches the homelab; the cache purge on publish is already in place.

TraderBuddy architecture: the stack and the constraints behind it

Mon, 12 Oct 2026 08:20:00 GMT

What the system is made of, and the handful of constraints that explain why it is shaped this way rather than some more obvious way.

What TraderBuddy is

A self-hosted trading dashboard for about five people: live quotes, server-computed indicators, drawing tools, price alerts delivered to Slack, macro context, and a manual portfolio tracker. It runs on a three-node Talos cluster on Proxmox, behind Cloudflare.

It tracks and alerts. It never trades. There is no order entry, no broker connection, no paper trading — even though the charting frontend is forked from a project that had all three. The portfolio is a manual ledger you type into. This is a product decision, not a missing feature.

(Diagram: view it on the website.)

Components and the traffic between them.

The stack

Layer	Choice	Why this one
Backend	Python 3.12, FastAPI, SQLAlchemy 2.0 async, asyncpg	Async throughout because most request time is provider I/O. `mypy --strict` over all of `api/src`.
Frontend	Vite 6, React 19, TypeScript, TanStack Query, zustand	A fork of OpenCharts (MIT), pruned to charting only.
Charts	lightweight-charts, pinned at 4.2.3	Pinned exactly, with `attributionLogo` on — Apache-2.0 attribution is a licence condition, not a preference.
Tables	@tanstack/react-table 8.21.3	Pinned to v8 on purpose; see "Deliberate deviations" below.
Database	PostgreSQL via CloudNativePG	Everything durable. Sessions and queues included.
Cache	Valkey	Short-TTL caching and rate-limit buckets only. Nothing here is a source of truth.
Identity	Zitadel OIDC, BFF session pattern	The browser holds an opaque signed cookie. No JWT ever reaches it.
Indicators	pandas-ta-classic, pinned exactly	Computed in Python only. The frontend never calculates.
Market data	Alpaca (bars, quotes, news, corporate actions), Finnhub (fundamentals, earnings), FRED + Shiller (macro)	All free tiers. All keys server-side.
Cluster	Talos v1.14, Kubernetes v1.36, Cilium v1.20 Gateway API	Gateway API, not Ingress and not Traefik.
Delivery	GitHub Actions → GHCR → Argo CD	Two repositories; see Deploy.

Four workloads, one image

The Python codebase ships as a single tb-api image with four entrypoints. Each Deployment runs a different command. There are deliberately not four backend images.

Workload	Entrypoint	Shape	Does
`tb-api`	`entrypoints/api.py`	2 replicas	The HTTP API and the `/ws` fan-out
`tb-stream`	`entrypoints/stream.py`	1 replica, `Recreate`	Holds the single upstream Alpaca WebSocket and republishes to Valkey pub/sub
`tb-alerts`	`entrypoints/alerts.py`	scheduled	Evaluates price alerts after the close
`tb-ingest`	`entrypoints/ingest.py`	scheduled	Symbols, bar retention, macro, portfolio snapshots, digest, scan

The constraints that shaped everything

One WebSocket, thirty symbols

Alpaca's free plan allows one WebSocket connection per account and 30 subscribed symbols. That single fact produces most of the streaming design:

tb-stream is a singleton with strategy: Recreate, because two pods briefly coexisting means a 406 connection limit exceeded and no live prices for anyone.
Users express interest in symbols; a budget allocator picks which 30 get the live feed, holding a symbol for 60 seconds after interest drops so a tab switch doesn't thrash subscriptions.
Symbols outside the budget are polled from a cached snapshot about every 15 seconds and labelled delayed in the UI rather than silently shown as live.

(Diagram: view it on the website.)

One upstream connection, fanned out through Valkey to every browser.

Real-time is IEX; history is SIP

Live quotes come from IEX, which is a few percent of US volume. Historical bars come from SIP, which is consolidated and authoritative — but the free plan embargoes the last 15 minutes of SIP, and rejects the entire request with a 403 if end falls inside that window rather than trimming it. AlpacaClient.get_bars clamps a SIP end clear of the window for that reason.

The consequence users see: an intraday chart can disagree with an alert until the close, because alerts evaluate SIP bars afterwards. The UI labels which feed a chart is showing instead of pretending they're the same.

Alerts need previous state

Condition alerts (a moving-average cross, a new high, a volume spike, RSI, a percent move) answer a question about a whole session rather than watching 1-minute bars for a touch, so they take their own path: alerts/conditions.py is pure — daily bars in, a verdict out — and calls the same pandas-ta functions that draw the chart's indicators, so an alert cannot disagree with the line the user is looking at. Daily bars are fetched split-adjusted; level alerts stay on raw prices because a level is a raw price. A condition has no price, so alerts.level is nullable, held honest by CHECK constraints, and the chart never draws a line for one. A cross is two consecutive sessions on opposite sides of the line, which is where "previous state" comes from without storing any.

An alert fires on a crossing, never on value > threshold. That distinction requires knowing the previous close, which is why alerts are evaluated once per trading day, server-side, on the session's SIP 1-minute bars — never on ticks, never in the browser. Dragging an alert line past the current price doesn't fire it: the baseline resets and only bars after the edit count.

Money is Decimal, and strings on the wire

Money and share quantities are Decimal in Python and strings in JSON, never JSON numbers — 1234.56 is a float to every client. The frontend formats them and does no arithmetic on them.

This is not pedantry. The portfolio ledger's property-based test caught a real bug this way: quantity * (price − avg) and quantity * price − quantity * avg round differently once average cost is a repeating decimal, and the books failed to balance by one ulp. Replay now quantizes to the column precisions, so what it computes is exactly what Postgres stores.

Privacy, and its one exception

Portfolios, alerts and watchlists are scoped to the session user — someone else's id returns 404, not 403, so the API never confirms which ids exist. Notifications go only to destinations that user connected themselves — their own Slack (a direct message, or a channel they choose), Telegram chat or webhook. The shared Slack bot is DM-only: its post() refuses anything but a DM, because a channel would show every user everyone else's holdings. A user-owned Slack token is different — workspace, app and destination are all theirs — so it may post to a channel they pick, and the UI says plainly that everyone in it can read the alerts.

Accounts. Zitadel authenticates; TraderBuddy authorizes. Registration is open, but every new user is pending and can read only /api/me until an admin approves them — over HTTP and over the WebSocket, which authenticates separately and needed its own check. projectRoleCheck is off in Zitadel precisely so a newcomer gets a waiting screen rather than an error page. The admin role still comes from Zitadel's project-role claim.

Credentials users enter. Slack and Telegram tokens and webhook URLs are encrypted at rest with Fernet (CREDENTIAL_KEY), as a whole blob rather than selected fields, because a webhook URL can carry a token in its path. The API is write-only for them — nothing returns a credential, so there is no "show token" — and no admin route touches the table. Webhooks are the one feature that lets a user aim the server at an address of their choosing, in a cluster that also runs Zitadel, Postgres and the Kubernetes API, and egress is not restricted, so the guard is the only defence: HTTPS only, every resolved address checked, then the connection made to the address that was checked rather than the name (a second DNS lookup would allow rebinding), no redirects.

The one exception, decided 2026-10-03: a user holding the Zitadel admin role can read any user's watchlist and portfolios, and a count of their active alerts, through /api/admin/*. It is read-only, it 404s for everyone else, and it carries two conditions — every cross-user read writes an admin_audit row, and the settings dialog tells every user this is possible. Searches are not logged anywhere.

Request paths

A normal API call

Browser → Cloudflare → Cilium Gateway → tb-api. The session cookie resolves against a sessions row in Postgres. Zitadel is never called on a normal request — no introspection endpoint — because it runs a single replica and would be a hard dependency on every page load. Roles are a snapshot taken at login and refreshed on token refresh.

A live price

Alpaca → tb-stream → Valkey pub/sub → every tb-api replica → each browser's /ws. Fan-out through Valkey is what lets tb-api scale to two replicas while only one upstream connection exists.

A chart

GET /api/bars reads closed bars from the Postgres cache, backfills from Alpaca only when the newest cached bar could be stale, and appends one live forming bar from IEX in two narrow cases. Closed bars are immutable once written.

An agent call

A coding agent speaks MCP to /api/mcp/ with Authorization: Bearer tb_pat_…. A door in front of the mount checks the token (SHA-256 lookup in Postgres; Zitadel is never involved) and each tool then calls the app's own REST routes in-process, carrying the same token. So validation, the approval gate, per-user scoping and rate limits are the browser's, not a copy of them. A token user has no roles, and what a token may reach is a fail-closed method-and-path allowlist in auth/tokens.py. See Connect a coding agent.

The scanner snapshot

After each close, tb-ingest scan fetches split-adjusted SIP daily bars for the shared universe (S&P 500, a few Nasdaq-100 extras, ~100 curated ETFs) plus every symbol anyone watches or holds, computes the moving averages, RSI, highs, volume and cross events once per symbol with the same pandas-ta calls the chart uses, joins cached Finnhub fundamentals, and writes one scan_snapshot row each. It is all-or-nothing: if a fetch fails the previous night's snapshot stands. Scans read that table and never a provider. Fundamentals are refreshed 150 symbols a night, paced under half the shared Finnhub budget, so they are up to a week old.

A scan is a validated list of filters (scanner/filters.py) compiled to SQL from a field whitelist, so no string a user sends is ever an identifier. Each query is restricted to is_core OR symbol IN (your watchlist and holdings): the snapshot contains rows that exist only because one person holds a symbol, and they must never appear for anyone else. "New" is computed by running the same filters on the previous session's snapshot, which is kept for two weeks, so there is no extra table.

Once the snapshot is committed the same job sends each user's notifying scanners (scanner/notify.py): every scanner of theirs with notify on is run through the same query.run as the page, so the privacy restriction is identical, and the matches go out as one message through notify/dispatch.py to that user's own channels. A scanner_notifications row is claimed per user per session before sending, as the digest does, so a rerun never posts twice; a send that fails everywhere releases the claim for the retry.

Company financials

Statements come from SEC EDGAR, which is free and keyless and which the browser never calls. Every request carries a User-Agent naming a project contact address, and goes through a Valkey token bucket at 8 requests a second (the SEC allows 10) shared by both API replicas and the nightly job. For a symbol, financials/service.py serves a stored report younger than a day; otherwise it reads the company's small submissions list and recomputes only when a new filing accession has appeared or the scoring VERSION changed. A recompute parses the multi-megabyte companyfacts document down to the ~30 concepts we map and drops the rest before the next company.

Companies tag the same line differently and change tags over time, so each field takes the first mapped tag that has a value for each period; annual figures are 345–385-day facts with the latest filing winning restatements, and trailing twelve months is the last fiscal year plus this year's year-to-date minus last year's. Indicators and the score are pure functions (indicators.py, score.py): a piecewise-linear table per indicator, a pillar is the mean of its indicators, and the overall score is the weighted mean of the pillars that could be scored. Unknown is never zero — a missing input is skipped, and fewer than three scored pillars is no score. The report is stored in financial_reports with a small scan block; the nightly scan reads only that block in SQL, never the whole report, which is the memory lesson from 0.4.3. If the SEC is unreachable the stored report is served marked stale.

Deliberate deviations from the plan

Each of these is a place the implementation diverged from TRADERBUDDY-IMPLEMENTATION-rev2.md on purpose. They are recorded here because an undocumented deviation reads as a bug to the next person.

Plan said	Built instead	Why
A `symbol_profiles` table	One `symbol_facts` table with a `kind` discriminator	Profile, metrics and recommendations have identical shape and TTL. Three identical tables would be three places to change.
Baseline mode "swaps the candle series"	Hides the candles, adds a baseline series	The drawing manager, crosshair legend and bid/ask lines all hold a reference to the candle series. Removing it would leave them pointing at a disposed object.
`@tanstack/react-table`, version unspecified	Pinned to 8.21.3, not the current 9.2.4	v9 is a ground-up redesign (atom stores, a `Subscribe` HOC). A sortable positions table isn't worth guessing at an unfamiliar API.
Fall back to the last regular-session 1-minute bar if the SIP daily close includes extended hours	Use the daily close directly	Measured: it excludes extended hours. AAPL printed above its regular high after the bell and the daily bar still matched the regular session exactly. The daily close is the official consolidated close — the fallback would have been a downgrade.
Watchlist truncated when the Slack block budget runs short	Capped at 15 rows regardless	Slack's 50-block limit alone would allow ~1,600 rows. The cap exists because a DM listing forty symbols is unreadable.

Standing risks

tb-stream is a single point of failure. The free tier offers no fix. It is monitored, not solved.
Losing the pve2 host takes everything — etcd majority and two of three Postgres instances. The real fix is a third host, which doesn't exist.
Provider free tiers can change without notice. The provider layer is built so swapping one is a config change.
Five users share one quota. A sixth may need paid tiers, not more RAM.
Nothing here is investment infrastructure. Analyst consensus is opinion data; indicator crossings are not predictions.

Last updated 2026-10-06. The diagrams above are drawn from D2 source files kept with the project.

Everything TraderBuddy does

Mon, 12 Oct 2026 08:10:00 GMT

It tracks and alerts. It never trades.

A self-hosted terminal for the US market: a watchlist that opens on the day's moves, charts with every indicator computed on the server, alerts that reach your own Slack or Telegram after the close, a screener over ~600 symbols, company financials read straight from SEC filings, market-moving news with an AI's read of each item, an AI research assistant on your own key, and a portfolio you keep by hand. No broker connection, no order entry, and nothing about you sold to anyone.

(Interactive content: An example TraderBuddy chart: daily candles with a server-computed moving average, a price alert level drawn at 230 with its bell enabled, and a dashed average-cost line at 214 for a symbol held in a portfolio.. View it on the website.)

Your watchlist, and a page for every stock

TraderBuddy opens on your watchlist. Each stock shows its price, the day's move and a small chart of the last session, with SPY, QQQ, DIA and IWM above the list for the market's mood. Sort by your own order, % change or A–Z.

The watchlist beside the page for one stock (META): its alerts, key stats, analyst ratings and financial-health summary. Each row shows the day's move and a small chart of the session.

It knows what is yours. A dot marks what you hold and a bell marks stocks with active alerts.
Fresh while it matters. Prices refresh every 15 seconds while the market is open. When it is closed, the list says it is showing the last close.
A page for every stock (/stock/NVDA): the price and day change, a chart with 1D to 5Y ranges, what you hold in it and your alerts on it, market cap, P/E, dividend yield, beta, the 52-week range, analyst ratings, a financial-health summary and its latest news. Watch, Add alert and Ask AI are one tap from the top.
Made for a thumb. Swipe a row left to remove it, and Edit reorders with arrows. An empty list offers SPY, QQQ, AAPL, MSFT and NVDA in one tap each.

The chart

The full drawing chart is the Chart tab. Open a symbol and you get candles from one minute to one week, drawn from closed bars cached on the server with one live forming bar on top. Scroll back and deeper history loads.

The Chart tab: NVDA on 15-minute candles, the drawing tools on the left and the watchlist panel on the right.

Indicators, computed server-side. SMA, EMA, RSI, ATR, VWAP, MACD, Bollinger Bands and Stochastic. Your browser draws them; it never calculates them, so the chart and an alert can never disagree.
Drawing tools. Trendlines, horizontals, rectangles and text, with magnet snapping, undo and redo, and an object tree. Everything is saved per symbol and waiting when you come back.
Live where it counts. Real-time prices stream for the symbols you have open. The rest are polled and labelled delayed, so you always know which number you are looking at.
Baseline mode. Show closes against a reference instead of in absolute terms: since you added the symbol, 1W, 1M, 3M, YTD or 1Y. The legend names the reference price and its date.
Info and news beside the chart. Profile, P/E, P/B, dividend yield, beta, a 52-week range bar and analyst ratings, marked as opinion. News follows your watchlist and falls back to market news when it is empty.
Symbols you hold are marked. A dashed average-cost line on the chart and a dot in the watchlist, so a position never gets lost between pages.
Search from anywhere. ⌘K finds any symbol. ↵ opens its page, ⌘↵ adds it to your watchlist. What you type is never logged.
Usable on a phone. The chart keeps the screen: the toolbar is two rows, with Watchlist, News and Info together under one Panels button. Watchlist, Chart, Alerts and Portfolio are tabs along the bottom, and the rest, Scanner included, are under More.
Dark, light, or your device's choice. Pick the palette in Settings; it stays on that device. A market clock in the top bar says whether the market is open and when that changes.

Alerts

Draw a line where you care about the price, turn on its bell, and TraderBuddy watches that level for you. Or create one from the Alerts page, where every alert you own is listed, editable, renewable and deletable.

(Interactive content: How an alert travels: your alert, then after the US close the session’s one-minute bars are read once a day, and only if the previous close sat on the other side of your level does a message go to the channels you connected.. View it on the website.)

The timing is the part worth knowing before you rely on it: alerts are checked once per trading day, after the US close, on that session's one-minute bars. That is a deliberate trade — the real-time budget belongs to the charts you have open — and it means an alert tells you on the evening of the day something happened, not the second it happens. The single exception is opening movers, below.

The Alerts page: each alert with its condition, your note, whether it repeats, when it last fired and when it expires.

Price levels. Crosses above, below, or either. On a trendline, the level is read along the line at the moment of checking, so a sloping level stays correct as time passes.
Conditions, not just levels. A close crossing its SMA or EMA, a golden or death cross, a daily move of X%, a new 52-week or all-time high or low, a volume spike, or RSI crossing a level. Any symbol in the universe, ETFs included.
Told what happened. A condition alert says what occurred rather than quoting a number: "the 50-day crossed above the 200-day", not "value > threshold".
Your channels, your credentials. A Slack DM, a Slack channel you pick, a Telegram chat, or a signed webhook. Every enabled channel gets every alert, and one failing never costs you the others.
A lifecycle, not a graveyard. Alerts last 90 days and then wait for you to renew them, re-arm after they fire, and keep a per-alert history of what happened and when. Renew or delete in bulk.
The chart agrees with the server. A bell on the chart means a real alert exists on the server. You will never be shown one that isn't actually armed.

Scanner

Filter about 600 symbols — the S&P 500, Nasdaq-100 names, roughly 100 ETFs, plus anything on your own watchlist or in your portfolio — on price moves, the 52-week range, volume against its average, SMA 20/50/200, RSI, golden and death crosses, new highs and lows, P/E, market cap and financial health. Thirteen scans are built in. Duplicate one to edit it, or save up to 25 of your own.

The built-in Oversold scanner: what it looks for in plain words, then its matches as of the last close, with the new ones counted.

As of the close, Fri 9 Oct 2026

What this scanner looks for

Index: S&P 500 — the 500 largest US listed companies.
Change today: above 7% or below −7% — a move far outside a normal session.
Volume: above 2× its 20-day average — unusual participation, not a quiet drift.

Matches

Thu 8 Oct: MRNA — Volume 2.4× its 20-day average (New)
Fri 9 Oct: MRNA — +14.2% on the day
and twelve more S&P 500 names moved 7% or more that session

A real match: Moderna's 8–9 October spike, caught by a 7% move scan and a 2× volume scan.

Written in plain language. Every scanner explains itself as you build it: "Debt / equity: below 1× — total debt over equity; under 1 is a lighter balance sheet." You can add a description in your own words.
Honest about its clock. Results are a snapshot taken after each close, and the page says which close. Symbols that were not matching the session before are marked New.
It can come to you. Turn on Send matches to my channels — new matches only, or every match — and one message per evening lists what each of your scanners found, every symbol linking to its chart. Nothing is sent on a day nothing matched.
No false precision. A symbol whose value is unknown — no 200-day average yet, no P/E — never matches a filter on it, instead of being quietly counted as zero.

Financials

Search a company and TraderBuddy reads its latest 10-K or 10-Q from the SEC, names the filing it used, links to it, and turns it into one score with the five parts behind it.

(Interactive content: An example financial health score of 78 out of 100, broken into five pillars drawn on the same scale: profitability 86, cash flow 81, balance sheet 74, shareholders 68 and growth 52.. View it on the website.)

Every number in a sentence. Each indicator carries its value, a five-year trend, a good / fair / weak marker and one plain explanation: "Out of every $100 of revenue, $23 is left after the direct costs."
Two checks shown test by test. The Piotroski F-score's nine pass/fail tests and the Altman Z-score's safe, grey or distress zones, each displayed in full so the score is never a black box.
The statements themselves. Five years of income statement, balance sheet and cash flow, in line names a person recognises.
Unknown is never zero. A figure the filing does not report is left out. A part without enough data says so, and a company with too little to go on gets no score at all.
Banks are judged as banks. For banks and insurers the measures that do not apply are dropped rather than invented, and the page says which and why.
Not advice. The score summarises what a company reported about its past. It does not forecast the share price, and the page says so plainly.

The financial-health report for NVIDIA, worked out from its latest 10-Q, with the filing it used named and linked.

News, and what it probably means

One page for the posts, filings and headlines that move markets, read from free public sources every five minutes and listed newest first, each with who published it and a link to the original.

The News page: company headlines, and under one of them the AI's read, labelled as opinion, not advice. The month's AI spend is shown at the top.

Who it reads. Federal Reserve press releases and speeches, White House news, Donald Trump's Truth Social posts (through the independent archive trumpstruth.org), SEC 8-K filings of S&P 500 companies and the symbols you follow, and Finnhub market and company headlines.
An AI's read of each item. A model (Claude Haiku) says how much an item matters (low, medium or high), sums it up in a line, and names the companies or sectors it is likely to push up or down, and why, even when the item names no company. It is labelled as an AI's opinion, not advice, with the direction in words as well as colour.
Read once, for everyone. The request contains only the item. Nothing about what you hold or watch leaves TraderBuddy; which items matter to you is worked out afterwards, on the server.
A hard cap. AI reading stops at $10 a month, checked before every call, and the page shows how much of it is used.
Honest about its sources. A source that stops answering is named at the top of the page with when it was last read.

An AI research assistant

Pick a model and ask about one stock or a handful: "Compare AMD and NVDA", "What do AAPL's financials say?" It looks things up as it goes, and you see each lookup as it happens. It reads prices and indicators, SEC financials, news, macro series, the scanner and your own watchlist, alerts and portfolio, then answers with the evidence, the bull and bear case, what would change its mind, and how confident it is.

The AI research page: past conversations on the left, suggested questions, and the model picker under the question box.

It drafts; you decide. When it suggests an alert or a watchlist addition it shows a card. Nothing exists until you press Create, and then it goes through the same checks as the Alerts page. It cannot change anything by itself.
Your own OpenRouter key. Paste it once; it is encrypted and never shown again. You pay OpenRouter directly for what you use, with a spending meter and an optional monthly cap in Settings. There is no shared key.
Private conversations. They are kept and listed so you can return to them or delete them. Not even an admin can read them.
Web search is off by default and turned on per message.

Macro context

Eight series on one page: the 10-year and 2-year Treasury yields, the 10y−2y spread, the Fed funds rate, CPI, unemployment, the VIX and the Shiller CAPE. Every figure shows the observation date it belongs to, because a macro number without its date reads as today's when it can be months old.

Colour follows meaning rather than direction, and stops where meaning stops:

Series	When it rises
Unemployment, CPI, VIX, Shiller CAPE	Worse — more joblessness, faster inflation, more stress, a more expensive starting point
10y−2y spread	Better — it is the fall through zero that people watch as a recession signal
10-year, 2-year, Fed funds	Neutral — higher rates are good for savers and bad for borrowers; picking a colour would be editorialising

Portfolio

A ledger you keep yourself: buys, sells, dividends, splits and fees, typed in or imported from CSV with a preview and per-row errors first. There is no broker connection, by choice. Positions, profit and loss, and history are all derived by replaying what you entered. The page leads with market value, with today's change under it.

(Interactive content: An example portfolio chart with two lines from nightly snapshots: market value rising to 16,480 dollars and cost basis stepping from 10,000 to 14,000 dollars in the month money was added, so a deposit cannot be mistaken for a return.. View it on the website.)

Arithmetic you can trust. Money and quantities are exact decimals end to end, never floating point. Every edit replays the whole ledger, so a backdated sell that would oversell is refused and names the transaction it conflicts with.
Average cost, stated as such. Positions use average cost rather than tax lots, and the interface tells you that instead of letting you assume otherwise.
Allocation. By symbol or by sector, with Unknown shown rather than hidden when a sector isn't available.
Corporate actions flagged. Splits and dividends that look unrecorded are pointed out, and "Record it" pre-fills the transaction. Nothing is ever applied to your ledger automatically.

A daily digest, if you want one

Off until you turn it on, section by section. After the close on trading days, you get one message on the channels you connected, with any section that has nothing to say left out.

An example of how it arrives

Portfolios

Core · +$412 today, value $16,480 against $14,000 of cost.

Alerts

AAPL crossed above 230.00. The alert has re-armed.

Watchlist

MRNA +14.2% on 2.4× its usual volume.

News and earnings

Three headlines on symbols you follow, and who reports tomorrow.

It is sent at most once a day. A crash can make it skip a day; it can never send you the same day twice.

Opening movers

One hour after the US open, TraderBuddy looks for S&P 500 stocks running: up 5% or more on yesterday's close and trading at least twice their usual volume for those first minutes, measured against the same minutes of the last ten sessions, because volume is always heaviest at the open.

An example of how it arrives

Two S&P 500 names are running an hour into the session.

XYZ +6.4% on 3.1× its usual volume for this part of the morning.

ABC +5.2% on 2.2×.

Prices are 15 minutes delayed

This is the one thing in TraderBuddy that runs during the session, and it is a deliberate exception. It is off until you turn it on in Settings, next to the digest. It arrives on trading days only, at most once a day, and never on a quiet morning. The time is shown in your own time zone, and the message says plainly that its prices are the full-market feed, 15 minutes delayed.

Let a coding agent use it

Claude Code, Cursor and other MCP clients can look symbols up, read your alerts and portfolios, and manage alerts, your watchlist, drawings, saved scanners, the digest and your portfolio transactions on your behalf. Create a token in Settings, paste the URL into your client, and ask in words: "what is NVDA's RSI doing, and alert me if it crosses 70". The step-by-step setup is in How to connect an AI agent to TraderBuddy over MCP.

{
  "mcpServers": {
    "traderbuddy": {
      "url": "https://trader.smkabir.com/api/mcp/",
      "headers": { "Authorization": "Bearer tb_pat_…" }
    }
  }
}

A token is shown once, expires between 30 days and a year, and is revoked rather than deleted. It can be read-only or read-and-write. A write token can add and correct portfolio transactions, but never delete one. What it can never touch is fixed in the server, not in the client: your notification credentials, the admin area, deleting from your portfolio, and minting more tokens. And since TraderBuddy has no order entry at all, no agent of yours can place a trade.

Where your data sits

Your browser talks to one server. Only TraderBuddy's own. No analytics, no third-party widgets, no market-data provider called from your machine. Every provider key stays server-side.
Searches are not recorded. Nothing logs what you type into ⌘K or the symbol box. Not for you, not for an admin.
Holdings and alerts are private. Every portfolio, alert and watchlist route is scoped to you; someone else's id simply does not exist. Notifications go to destinations you connected yourself, never a shared channel.
Credentials are write-only. Slack and Telegram tokens, webhook secrets and your OpenRouter key are encrypted at rest and never returned by any route, to you or to anyone. To change one you replace it.
What the AI sees, stated. The news reader is sent only the news item. The research assistant, when you use it, sends market data and, when relevant, your watchlist, alerts and portfolio to OpenRouter and the company running the model you chose. TraderBuddy asks for providers that do not keep or train on it, and the AI page says all of this before you paste a key.
The admin exception, stated. An admin can read any user's watchlist, portfolios and alerts — read-only. Every such read is recorded in an audit log, and the app tells every user this is possible. Your searches, AI conversations and channel credentials stay out of reach.
Getting an account. Anyone can register; nobody gets in until an admin approves them. Until then you see a waiting screen and nothing else.

What it deliberately does not do

These are choices, not gaps, and they are not going to change:

Place orders. No order entry, no broker positions, no depth of market, no paper trading.
Connect to a brokerage. The portfolio is typed in or imported from a CSV.
Track tax lots. Average cost only, and it says so where it matters.
Fire alerts on ticks. Once per trading day, after the close.
Calculate anything in your browser. Indicators, crossings and signals are all server-side.
Give advice. Analyst consensus is opinion data, an indicator crossing is not a prediction, a financial score is a summary of past filings, and an AI's read is an analysis, not a recommendation.

Features as of version 0.18.0, 18 October 2026. Example figures are illustrations, not real data.

TraderBuddy in thirty seconds

Mon, 12 Oct 2026 08:00:00 GMT

Thirty seconds, seven scenes, on a loop: what TraderBuddy is for, in the order you would meet it. The sequence is drawn live in your browser from a few hundred lines of script, with no video file behind it, so you can pause it, restart it, or jump to any scene.

(Interactive content: TraderBuddy in thirty seconds: an animated title sequence. View it on the website.)

The seven scenes

Thesis (0:00). It tracks and alerts. It never trades.
The chart (0:03). Candles building, with a server-computed moving average.
The alert (0:09). A price level armed at 230, and delivered only after the US close.
Scanner (0:16). About 600 symbols narrowed to 13.
Financials (0:21). A filing from the SEC becomes a financial health score of 78, in five parts.
Portfolio (0:25). The cost line steps up when money is added, so a deposit is never mistaken for a return.
Lock-up (0:28). The name and the one-line claim again.

TraderBuddy checks alerts once a day, after the close, so the film never shows one firing mid-session. It also never shows an order ticket: there is no order entry anywhere in the product.

Keep reading

Everything TraderBuddy does: the feature tour, with the illustrations and example messages.
Architecture and tech stack: what it is built from, and the provider limits that shaped it.

What the homelab costs to run, in yen

Sun, 04 Oct 2026 09:00:00 GMT

Two Intel N100 mini PCs, a small backup box, a USB disk, a switch and a UPS run around the clock in my flat in Tokyo. They host this blog, its CMS, TraderBuddy, AiBuddy, Argo CD and the monitoring stack. An earlier version of this post used sample figures. This one uses TEPCO's current tariff, the real hardware and 30 days of load data, and then prices the same capacity on AWS and DigitalOcean.

Short answer: about 39 W around the clock, 28.5 kWh a month, ¥1,024 a month or about ¥12,300 a year in electricity. Renting the same four VMs costs about ¥30,400 a month on DigitalOcean and ¥56,900 a month on AWS in Tokyo.

The hardware

Device	Role	Est. watts
TRIGKEY Key-N (pve1): N100, 4 cores, 16 GB	Proxmox: one control-plane VM, the worker VM, two small guests	11
TRIGKEY Key-N (pve2): N100, 4 cores, 16 GB	Proxmox: two control-plane VMs	11
BMAX B1 Pro-class Celeron box (qdev-pbs)	Quorum tie-breaker, Proxmox Backup Server, etcd snapshots	4
USB hard disk	Backup datastore	5
Gigabit switch	Joins the boxes to the router	3
CyberPower SX550U UPS	Its own electronics and charging losses	5
Total at the wall		≈ 39

The ISP's router is not on the list. The house would run it anyway.

Where the watts come from

I have not put a watt checker (ワットチェッカー (watto chekkā, plug-in power meter)) on the power strip yet, so each figure starts from a published wall measurement and is adjusted for how busy the box really is. Over the last 30 days Proxmox reports about 13–17% average CPU on pve1 and 16–21% on pve2: light, but never idle, because etcd, Prometheus and the TraderBuddy jobs keep the cores ticking.

N100 hosts, 9–14 W each. Measured N100 mini PCs idle at about 6–9 W and reach 21–26 W at full load. A Proxmox N100 box running containers measured 11–17 W. I use 11 W.
qdev-pbs, 3–6 W. A B1 Pro-class Celeron box idles at about 3 W headless. It mostly waits for heartbeats and wakes for the nightly backup.
USB disk, 2–7 W. The widest range: about 2 W for a 2.5-inch portable drive and 5–7 W for a spinning 3.5-inch drive in a powered enclosure.
UPS, 3–8 W. CyberPower does not publish a no-load figure for the SX550U, so 5 W is an assumption.

What TEPCO charges per kWh

The house is on TEPCO's regulated plan, 従量電灯B (jūryō dentō B, metered lighting B), whose rates changed on 1 November 2026. The lab only adds kWh on top of the household's use, so the price that matters is the marginal one. A typical household (TEPCO's model is 260 kWh a month) is in the second tier, so the lab's kWh are billed there.

Line on the bill (per kWh, tax included)	Nov 2026	Dec 2026
Energy charge, 120–300 kWh (電力量料金 (denryokuryō ryōkin, energy charge))	¥36.45	¥36.45
Fuel cost adjustment (燃料費調整額 (nenryōhi chōseigaku, fuel cost adjustment))	−¥5.33	−¥4.65
Renewable energy surcharge (再エネ賦課金 (saiene fukakin, renewable energy surcharge), FY2026)	¥4.18	¥4.18
Marginal price	¥35.30	¥35.98

I use December's ¥35.98, the latest confirmed figure. The government's 電気・ガス料金支援 (denki gasu ryōkin shien, electricity and gas bill support) discount covered October only, so none is included. The base charge (¥1,176.18 for 30 A) does not count: 39 W will never push the house into a bigger ampere contract.

Rule of thumb: at ¥35.98 per kWh, every watt that runs 24/7 costs about ¥26 a month, or ¥315 a year.

The electricity bill, three ways

Scenario	Draw	kWh / month	¥ / kWh	¥ / month	¥ / year
Low: near idle, 2.5-inch disk	28 W	20.4	35.98	735	8,830
Central estimate	39 W	28.5	35.98	1,024	12,290
High: busier hosts, 3.5-inch disk, house in the third tier	54 W	39.4	40.07	1,580	18,950

Months are 730 hours. Above 300 kWh a month the tier price is ¥40.54 − ¥4.65 + ¥4.18 = ¥40.07, so in a cold winter month the same 39 W costs about ¥1,140 instead of ¥1,024.

The same capacity on AWS or DigitalOcean

The cluster is four Talos VMs: three control-plane nodes with 2 vCPU and 5 GB each, and a worker with 2 vCPU and 6 GB. That is 8 vCPU, 21 GB of RAM and 280 GB of disk. No cloud plan sells 5 GB, so every option below rounds up to 8 GB per node. I priced two ways to rent it: four plain VMs running the cluster exactly as I do now, and a managed Kubernetes service that replaces the three control-plane VMs. Prices are on-demand, in US dollars, converted at ¥158.29 to the dollar (ECB, 3 November 2026).

Option	What you rent	$ / month	¥ / month	¥ / year
Homelab (electricity)	Hardware already owned	6.47	1,024	12,290
DigitalOcean Droplets	4 × Basic 4 vCPU / 8 GB ($48, 160 GB SSD and transfer included)	192.00	30,392	364,704
DigitalOcean Kubernetes	3 × the same nodes, HA control plane ($40), 100 GB volume	194.00	30,708	368,496
AWS EKS, Tokyo	EKS cluster ($73), 3 × t3.large, 220 GB gp3, 3 public IPv4	343.34	54,348	652,176
AWS EC2, Tokyo	4 × t3.large (2 vCPU / 8 GB, $0.1088/h), 280 GB gp3, 4 public IPv4	359.18	56,854	682,248

The AWS lines break down like this: a t3.large in Tokyo is $0.1088 an hour, or $79.42 a month. gp3 storage is about $0.096 per GB-month in Tokyo. Each public IPv4 address is $0.005 an hour, about $3.65 a month. An EKS cluster is $0.10 an hour on standard support. DigitalOcean includes disk and transfer in the droplet price and does not charge for IPv4. Its Kubernetes control plane is free, and $40 a month makes it highly available, which is what my three etcd members give me.

DigitalOcean has no Japan region. The nearest is Singapore, so every request from Tokyo would make a longer round trip. AWS Tokyo is next door.
A t3.large is burstable. Its baseline is 30% of each vCPU. My nodes average under 20%, so they would fit, but the nightly TraderBuddy backfills would spend CPU credits.
Cheaper AWS options exist. A Graviton t4g.large is $0.0864 an hour in Tokyo, but my images are built for amd64. Savings Plans and Reserved Instances lower the EC2 line if you commit for one or three years. I priced on-demand because the homelab has no commitment either.
Backups and egress are not in the cloud figures. Adding the nightly backups and the outbound traffic would only raise them.

Against the cheapest cloud option, the homelab saves about ¥29,400 a month. If the hardware cost ¥150,000 in total, it paid for itself in about five months. Even with the mini PCs replaced every four years, the electricity-plus-hardware total stays a small fraction of the cloud bill.

The cloud price buys things the homelab does not have: a datacentre with redundant power and network, a provider SLA and hardware nobody has to repair. My whole cluster shares one house, one ISP, one switch and one UPS. For a personal lab that trade is fine. For a business it usually is not.

What this number leaves out

The hardware. Spread over four or five years, depreciation is probably larger than the electricity.
The fibre line and router. The house pays for these anyway.
Domain and Cloudflare. The tunnel and the R2 buckets fit the free tiers. The domain is a few thousand yen a year.
UPS batteries. A real cost every few years.
Summer cooling. About 39 W of extra heat adds a little to the air conditioner's work.

Turning the estimate into a measurement

The weakest link is the watts. A plug-in watt checker between the wall and the UPS would replace six estimates with one measured number. When I have it, I'll update this post. Until then, ¥1,000 a month is the central figure, and the real one is very unlikely to be above ¥1,600.

Sources

How this site is built: a static blog on a homelab

Mon, 28 Sep 2026 09:00:00 GMT

This site is a static Astro build. The words live in a headless CMS, but readers never touch it: they get plain files from nginx (or from a mirror in object storage when the homelab is down).

The shape of it

Publishing in the CMS triggers a build. The build produces a dist/ folder, uploads it as a numbered release, and moves a pointer. The pods notice the new pointer and swap their content without a rollout.

(Diagram: view it on the website.)

How releases are laid out:

Static output, one folder per release
1. Pointer file names the live release
2. Rollback rewrites the pointer
Content-sync sidecar pulls the new release

Where the site build stands:

[x] Type check clean
[x] Pagination tried with a small page size
[ ] First real post written

Why not just render pages from the CMS?

Availability: a static file keeps working when the database does not.
Cost: no application runtime on the read path.
Security: the CMS is only reachable behind an access gate.

A static site on a single-house homelab is strictly less available than a hosted static platform. The point of running it here is to learn, which is why a failover mirror exists.

Typed content, end to end

The schema is code. Types generated from it are imported by the site, so a schema change that breaks a page fails the type check before it fails a reader.

import type { Post } from '~/lib/types';

export function hasPage(post: Post, locale: Locale): boolean {
  return post._status === 'published' && post.publishedIn[locale] === true;
}

Building it

A local build is two commands:

$ pnpm install --frozen-lockfile
pnpm build
i18n: 96 keys present in all locales
[build] 24 page(s) built in 3.1s
[build] Complete!

Published URLs are permanent. Changing a slug without a redirect is a bug.

More in the next part, where the CMS goes into the cluster. See the homelab write-up for the platform.

An interactive demo

Posts can include small interactive pieces written as plain HTML and JavaScript. They run in a sandboxed frame, so they cannot touch the site around them or send anything anywhere.

(Interactive content: A line that grows with each button press. View it on the website.)

The Japanese words that paperwork actually uses

Tue, 15 Sep 2026 09:00:00 GMT

Everyday life in Japan runs on forms. A handful of words cover most of them, such as 本免許 (honmenkyo, full driving licence) and 表札 (hyōsatsu, nameplate). Hover or tap a term to see the English.

A placeholder figure with a caption.

Cars have their own vocabulary too. The plate on the back is the ナンバープレート (nanbā purēto, number plate), and it is one of the first things to hide in a photo.

Before publishing any photo, check the plate, the nameplate, street signs and reflections. See the checklist in the editor.

If you have a favourite word that tripped you up, tell me.