Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

22.1 KB
Raw Blame

Home plans, entitlements and quotas

How three.ws decides what a connected house costs, what each plan covers, and the two things no plan may ever refuse.

This document is both the reference for the mechanism and the pricing proposal put to the owner. Every number in the plan table is a proposal with a measured cost behind it, and every number is a config value: applying an owner-approved figure is an environment variable on a running service, not a deploy.

Related: docs/smart-home.md (what the lane is), docs/home-privacy.md (retention and deletion), docs/home-households.md (roles and seats).


The two commitments to read first

1. A limit never blocks a safety action. Over quota, past due, downgraded, paused: a user can still lock their door, close their garage, close a water valve and arm their alarm. The safe direction is always free. A product that will not let someone lock up because they hit a quota is indefensible.

2. Nothing about the gate is a paid feature. Confirmation prompts, the action log's integrity and every safety property of the role system exist on every tier, including the free one. There is no metered dimension for any of them and there must never be one. Selling safety would be wrong, and it would also make the free tier a liability.

Both are enforced in code rather than promised in prose. api/_lib/home/entitlements.js checks the safety exemption before it looks at any counter, any plan or any pause state, and it gets the list of safe moves from packages/home-bridge/src/safety.js rather than keeping a copy that could drift. tests/home-entitlements.test.js asserts both, first in the file.


The cost model, measured

The Home lane's cost model is unusual, and the unusual part decides the shape of the plans: the expensive thing is not an action, it is a held socket. A house that is connected and idle occupies heap on a Cloud Run instance for the whole month whether or not anybody speaks to it, so a plan metered only on actions would charge nothing for the dominant cost.

Everything below was measured, not assumed. Re-derive it with:

node scripts/home-test-instance.mjs --up --onboard --seed --json --name cost
node --expose-gc scripts/measure-home-entitlement-cost.mjs \
  --url http://127.0.0.1:<port> --token "<token>" --homes 16 --rates

--rates reads the live Cloud Run prices from Google's own Cloud Billing Catalog API rather than from a remembered figure. The production service shape comes from gcloud run services describe three-ws-api --region us-central1: 4 GiB, 2 vCPU, concurrency 160.

Dimension Measured marginal cost How it was read (2026-09-03)
A connected home $0.0155 / home / month 16 real WebSocket connections to a real Home Assistant (125 entities): 302 KB heap, 262 KB RSS marginal per connection. At 60% of a 4 GiB instance that is ~9,800 homes per instance; the instance costs $152.42/month at $0.0000025/GiB-s + $0.000024/vCPU-s
An open live stream $0.0066 / stream / month a 23,036-byte room graph, serialized once per 10 s, at the same rates
An agent turn, default chain $0 the default provider chain leads with platform-held free lanes (isFreeLane in api/_lib/llm-pricing.js)
An agent turn, Vertex Gemini 2.5 Flash $0.0025 costMicroUsd over the real 6,359-token home prompt (the room graph) plus 250 output tokens
An agent turn, Claude Haiku 4.5 $0.0076 same prompt, same function
An agent turn, Claude Sonnet 5 $0.0228 same prompt, same function
A voice minute $0 the default lanes are keyless: Edge Read Aloud TTS (api/_lib/tts-edge.js) and NVIDIA Riva ASR (api/_lib/asr-nvidia.js)
An action-log row negligible a busy evening of voice control is a few dozen rows of a few hundred bytes

What that measurement changed

Two findings inverted the assumptions this work started from, and both are worth stating plainly because they point the pricing in the opposite direction:

One agent turn on a paid model costs weeks of holding that house's socket. $0.0228 for a single Claude Sonnet 5 turn, against $0.0155 per home per month: about six weeks of connection for one sentence. The connection is not the expensive part after all; the prompt is, because the room graph makes a home prompt large.

That ratio was re-measured on 2026-09-09 against a second real Home Assistant and it does not come back identical, so the honest version is a range rather than a point. The heap figure reproduces almost exactly (309 KB marginal per connection against the original 302 KB) and the stream figure reproduces to the cent, but resident memory does not: 1.25 MB marginal per connection against the original 262 KB, which prices a home at $0.0738/month instead of $0.0155. The re-measurement ran on a machine at load 83 with several other agents building, and RSS under memory pressure includes a great deal that is not attributable to the connection, so $0.0155 remains the figure to price from and $0.0738 is a defensible upper bound. Priced at the upper bound a Sonnet turn still costs nine days of holding the socket, so the conclusion below is unchanged at either end of the range, which is the only reason this is a footnote and not a re-plan.

Voice is not a cost driver at all. The default speech lanes are keyless and cost the platform nothing per utterance. Voice minutes are metered because an unbounded always-listening satellite is an abuse surface and because a paid speech lane can be selected, not because the default costs money.

Can the free tier carry a connected home?

Yes, comfortably. At 1.6 cents per home per month, ten thousand free connected homes cost about $155 a month, which is roughly one warm Cloud Run instance. At the loaded-machine upper bound above the same ten thousand homes cost about $740 a month, which is still a rounding error against the credit grant and still does not change the answer. The honest constrained free tier some cost models would have forced (a session-scoped connection that closes when the tab does) is not necessary and would make the free tier worse for no saving worth having. The free tier gets a real, persistent, always-connected home.

The dimension that actually needs a ceiling is the agent turn on a paid model, and that is where the tiers separate.


The dimensions

Dimension Scope Period Scales with $THREE Why it is metered
homes account concurrent yes the held socket, the lane's primary cost
members per home concurrent no the enterprise dimension: seats are sold, not held
streams per home concurrent yes a wall display is a subscriber we serialize the house to
voiceMinutes account monthly yes abuse surface, and a paid speech lane can be chosen
agentTurns account monthly yes the only dimension where a turn can really spend money
logRetentionDays account ceiling yes a hotel needs a year of attribution, a household needs last Tuesday
relayConnections account concurrent yes a dial-out tunnel costs what a direct connection costs

members deliberately does not scale with the $THREE ladder. Holding a bag and buying seats for a hotel are different purchases, and multiplying one by the other prices neither correctly.

logRetentionDays is a ceiling on what a user may set, never a value of its own. api/_lib/home/privacy.js owns the per-home retention setting, its 90-day default and the purge. The ceiling is checked when the user raises the setting and is never applied retroactively: shortening somebody's existing audit trail for a billing reason would destroy their evidence, and the log's integrity is not for sale on any tier.


The proposed plan table

This table is a proposal. Nothing here is a decided price.

Dimension User (free) Beta Pro Three Dimensional
Connected homes 1 2 5 unlimited
Household seats per home 3 5 15 unlimited
Live streams per home 2 3 10 unlimited
Voice minutes / month 300 600 3,000 unlimited
Agent turns / month 1,000 2,500 15,000 unlimited
Action-log retention 90 days 90 days 365 days 3,650 days
Relay connections 1 1 5 unlimited

Reasoning, dimension by dimension:

  • Homes at 1 on free is not a cost constraint (a free home costs 1.6 cents a month). It is the natural upgrade trigger: the second house is a household with an office or a parent's place, and that is a person who has already decided the product is worth something.
  • Turns at 1,000 free covers roughly 33 agent conversations a day. On the default free LLM chain that costs the platform nothing; on Sonnet 5 it would be $22.83, which is why the ceiling exists at all. Pro's 15,000 is $342 at Sonnet prices and $0 on the default chain, so the number to watch is the paid-model mix, not the turn count.
  • Voice at 300 minutes free is five hours of speech a month. It costs nothing today; the number is an abuse ceiling, and it should move the day a paid speech lane becomes the default.
  • Seats at 3 free is a household. 15 on Pro is a small office. A hotel is an override, not a tier, which is exactly the point of the override row.
  • Retention at 90 days free deliberately equals the platform default, so no existing home is retroactively over its ceiling the day this ships. Pro's 365 is the compliance answer; 3,650 is the schema's hard maximum and promising more would be a promise the database refuses.

The holder badge intentionally carries the same base numbers as user: holding $THREE raises quotas through the ladder's existing rateMultiplier (2x Bronze through 10x Genesis) rather than through a second set of thresholds. A Genesis holder therefore gets 10 homes and 10,000 turns without any of that being modelled twice.

Applying a number

Every limit is env-overridable as HOME_LIMIT_<TIER>_<DIMENSION> in upper snake case:

gcloud run services update three-ws-api --region us-central1 \
  --update-env-vars HOME_LIMIT_PRO_HOMES=25,HOME_LIMIT_USER_AGENT_TURNS=1500

unlimited and -1 both mean no limit. An unparseable value is ignored and the default stands, because a typo that resolved to zero would lock somebody out of their own house. Note --update-env-vars, never --set-env-vars, which replaces the whole environment.


Per-account overrides: the enterprise row

Enterprise limits are configurable per account rather than hardcoded, because that is what the sales conversation is. A hotel does not buy "Pro", it buys 400 rooms and a year of attribution, and the shape of that deal is known on the call and not at deploy time.

curl -X POST https://three.ws/api/home/plan \
  -H 'content-type: application/json' \
  -H "x-csrf-token: $CSRF" --cookie "$SESSION" \
  -d '{
        "action": "override",
        "user_id": "…",
        "limits": { "homes": 400, "members": "unlimited", "logRetentionDays": 730 },
        "note": "Hotel group: 400 rooms, one year of attribution. Agreed on the 2026-09-03 call."
      }'

Admin session only. Sending "limits": {} clears the override and returns the account to its plan. (For a bearer token rather than a session, GET /api/home/plan needs the home:read scope and every POST needs home:act, the same capability-to-scope rule the per-home routes apply.) An unknown dimension is dropped rather than stored, so a typo in a form cannot install a limit nothing reads. A dimension the deal did not mention keeps its plan value.

The note is not decoration: "why does this account have 400 homes" is a question somebody asks six months after the person who agreed it has moved on, and the answer has to be in the row.


The downgrade path

A downgrade never disconnects a house. When a plan change leaves an account with more connected homes than it covers, the excess are paused:

  • home_connections.deactivated_at and deactivated_reason are set. Nothing else changes.
  • The row survives. The encrypted access token survives. The action log survives with its lineage.
  • revoked_at is not set. Revoke is the user saying "take my house off this platform" and it scrubs the credential irreversibly; a pause is the platform saying "your plan covers fewer of these right now" and it must be reversible.
  • The oldest homes stay live by default, because they are the ones most likely to be the real house, and the user swaps freely at /smart-home/plan.
  • A paused home still answers safety actions. Locking up, closing a garage or valve and arming an alarm work on a paused home exactly as they do on a live one.

Bringing a paused home back while at the limit is refused with a designed message, not a 500, which is the whole reason a user pauses one first and resumes another.


Counters: one number, not two

agentTurns has no event kind of its own. A conversation with the agent already writes exactly one kind: 'chat' row into usage_events carrying the provider, model, token counts and priced cost (api/chat.js), and that row is what an invoice would charge for. Minting a second row beside it would mean two numbers that disagree, and the one on the invoice being wrong. So a home turn is the same row, distinguished by the home_id the chat handler stamps into its meta when a home tool ran.

voiceMinutes does get its own kind (home.voice), because nothing counted voice before: the TTS and ASR lanes write no usage events at all. That is a new fact, not a duplicated one.

Reads are cached in Redis per (account, dimension, month) and seeded from usage_events when cold, so the cache converges on the authoritative number rather than starting a private tally. A cache eviction while events are still in the write buffer under-counts for the rest of the month. That bias is deliberate: a quota that errs must err toward serving the user, and over-counting would refuse somebody access to their own house over a Redis hiccup.

Without Redis, every read goes straight to usage_events. Correct, just slower.

The quota period is the UTC calendar month. The platform has no per-user plan billing cycle to key off (users.plan is a column, not a subscription), and inventing one here would be a second billing clock that drifts from whatever the real one turns out to be. It resets on a date every user can predict, and it is shown on the plan page with that date.


Where enforcement happens

Point File What it refuses
Acquisition api/home/index.js a new home past homes, before any socket is opened. Reconnecting a house the account already has is an update, not an acquisition, so a token rotation is never refused
Stream api/home/[id]/stream.js a new SSE subscriber past streams, before any SSE head is written
Seats api/home/[id]/members.js an invitation past members, counting outstanding invites as well as members, billed to the home's owner
Retention api/_lib/home/privacy.js raising retention past the plan's ceiling. Never applied retroactively
Actions api/home/[id]/call.js an ordinary action on a paused home. The safety exemption is checked first, so a safety action is never reached by this code
Agent turns api/_lib/home/turn-gate.js, called from api/chat.js a home tool the agent tried to run past agentTurns. Read-only tools are never gated and safety actions are never gated, so over quota the agent can still be asked what the house is doing and told to lock up

Ordinary service calls are not metered at all. Actions are cheap; the socket is the cost. A user can run twenty lights all evening without touching a quota. What is metered is the agent turn that drives them, because on a paid model one turn costs weeks of holding that house's socket.

Two deliberate holes in the agent-turn gate, both of which exist so commitment 1 survives contact with a real conversation rather than only with a unit test:

  • Read-only home tools are never gated. The agent finds the door by reading the house (home_status) and only then targets the lock. Gate the read and the safety exemption ends one step before it was needed. A read also spends nothing the turn had not already spent by the time the model emitted the call.
  • A safety action inside a gated tool is never refused. home_call carries its domain and service on the input, which is exactly what the safety classifier reads, so a lock, a close or an arm is recognised with no live entity list and therefore in precisely the degraded states where somebody most needs to lock up.

Home tools are also only offered to the agent's owner. When a signed-in visitor chats with an agent they do not own, homeToolsOffered in api/chat.js withholds every home tool for that turn, because the other account's persona and custom skills share the prompt and the tools would run under the visitor's authority. A turn with no agent, or with the visitor's own agent, keeps them. That is a trust boundary rather than a quota, so it applies on every plan, and it does not touch the safety exemption: the exemption governs limits, not who may be offered a tool.

The gate also fails open. An unreadable entitlement row or an unreachable usage counter resolves to "allowed", never to "refused": a quota that errs must err toward serving the user, and refusing a person access to their own house over a billing hiccup is the failure this lane is least willing to ship.

And it resolves in two passes, so it does not put a Solana RPC on the chat critical path. resolveHomeEntitlementsFloor answers without reading the chain; because the $THREE multiplier is Math.max(1, ...) it can only ever raise a limit, so an account inside the floor is inside its real limit and nothing further needs to be known. Only an account that is PAST the floor pays for the full read, which is exactly the account whose holding might be the thing that raises its ceiling. A per-account override is applied after the multiplier in both passes, so it lands identically in each and the floor is never wrong about an enterprise row.

There is also a separate, unrelated ceiling: the per-instance backpressure ladder in api/_lib/home/admission.js. That answers "is this instance full"; this document answers "does your plan cover this". The two compose and neither replaces the other.


The plan page

/smart-home/plan shows every dimension whether or not it is near its ceiling, each with its usage, its limit, the reset date and the reason it is metered. A quota you only meet at the moment it refuses you is a quota nobody showed you.

It is also where a user swaps which homes are live after a downgrade, and where the two lines a limit can never touch are stated in words rather than buried in a policy nobody opens.


How the two commitments are verified

Both commitments are covered by tests that drive a real Home Assistant, not by unit tests over our own classifier. Bring a house up first:

node scripts/home-test-instance.mjs --up --onboard --seed --name plan19

Commitment 1, the safety exemption. The live block at the end of tests/home-turn-gate.test.js puts an account past every dimension at once (an override of 0 on all of them) and pauses its home the way a downgrade does, then asks the real house to lock a deadbolt, close a cover and arm the alarm. Each one asserts the state read back out of Home Assistant, so a pass means the device moved. In the same moment it asserts that an ordinary action and the unsafe direction of a safety domain are both still refused, because an exemption that is not selective is just a broken gate.

HOME_LIVE=1 HOME_LIVE_NAME=plan19 HOME_ALLOW_LOCAL_INSTANCE=1 \
  node --env-file=.env.local node_modules/.bin/vitest run tests/home-turn-gate.test.js

HOME_ALLOW_LOCAL_INSTANCE has to be exported before the run rather than set inside it: api/_lib/home-url-guard.js reads it into a module-level constant the first time it is imported, so a value set later arrives too late and every call is refused as a private address. The block fails with that explanation rather than the confusing symptom.

Commitment 2, the downgrade, and commitment 3, the quota display. The two journeys in tests/e2e/home-plan.spec.js open /smart-home/plan in a real browser against a real API and a real house. The first asserts every dimension renders with its usage and a real reset date before anything is near a ceiling. The second clicks Pause on a connected home and proves on screen that the row stays, is labelled paused, keeps its credential, and can be made live again.

HOME_E2E_ENC_KEY="$(node scripts/read-service-env.mjs '^WALLET_ENCRYPTION_KEY$' --raw)" \
  HOME_E2E_API_PORT=8171 HOME_E2E_WEB_PORT=3031 HOME_LIVE=1 HOME_LIVE_NAME=plan19 \
  npx playwright test --config playwright.home.config.js tests/e2e/home-plan.spec.js

HOME_E2E_ENC_KEY (or an exported WALLET_ENCRYPTION_KEY) has to be the key bound to the database in .env.local: api/_lib/secret-box.js refuses any other writer with secret_box_key_mismatch, and the global setup checks the binding before the first browser opens. tests/e2e/README.md has the details.

The journeys pause by clicking the button, never by posting to /api/home/plan directly: that route is CSRF-guarded like every other state change, so a raw request would have to mint a token the product mints for itself, and the test would then be exercising a path no user takes.