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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
#!/usr/bin/env node
/**
* A fleet of real Home Assistant instances, for the Home lane's load and chaos work.
*
* Every measurement in docs/ops/home-operations.md is taken against containers this
* script starts: real Home Assistant, real onboarding, real long-lived access
* tokens, real WebSocket handshakes. Nothing here simulates Home Assistant, and
* nothing here ever points at somebody's house. The only hosts it touches are
* containers on this machine.
*
* node scripts/home-fleet.mjs up --homes 10 # a small-house fleet
* node scripts/home-fleet.mjs up --homes 4 --big 1 --slow 1
* node scripts/home-fleet.mjs status
* node scripts/home-fleet.mjs down
*
* `up` writes a manifest to tasks/home/fleet.local.json (gitignored: it holds
* live tokens to running containers). scripts/home-load.mjs reads it.
*/
import { spawn } from 'node:child_process';
import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
import { createServer, connect as netConnect } from 'node:net';
import path from 'node:path';
import process from 'node:process';
import { fileURLToPath } from 'node:url';
import WebSocket from 'ws';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const MANIFEST = path.join(ROOT, 'tasks', 'home', 'fleet.local.json');
const CONFIG_ROOT = path.join(ROOT, '.home-fleet');
const IMAGE = 'ghcr.io/home-assistant/home-assistant:stable';
const NAME_PREFIX = 'threews-ha-';
const BASE_PORT = 18200;
const PASSWORD = 'threews-load-harness';
/** A "large house": the entity count order 14 measures the expensive end against. */
const BIG_HOUSE_ENTITIES = 500;
// ---------------------------------------------------------------- shell helpers
function run(cmd, args, { capture = true } = {}) {
return new Promise((resolve, reject) => {
const child = spawn(cmd, args, { stdio: capture ? ['ignore', 'pipe', 'pipe'] : 'inherit' });
let out = '';
let err = '';
child.stdout?.on('data', (d) => (out += d));
child.stderr?.on('data', (d) => (err += d));
child.on('error', reject);
child.on('close', (code) => {
if (code === 0) resolve(out.trim());
else reject(new Error(`${cmd} ${args.join(' ')} exited ${code}: ${err.trim() || out.trim()}`));
});
});
}
const docker = (...args) => run('docker', args);
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
/**
* Home Assistant runs as root inside the container and writes root-owned files
* into the bind-mounted config directory (blueprints, .storage, the database),
* so the host user cannot unlink them. Deleting them therefore has to happen as
* root too, and the cheapest root on this machine is the image we already have.
*/
async function removeAsRoot(target) {
const parent = path.dirname(target);
const leaf = path.basename(target);
await mkdir(parent, { recursive: true });
await docker('run', '--rm', '-v', `${parent}:/scrub`, '--entrypoint', 'rm', IMAGE, '-rf', `/scrub/${leaf}`).catch(() => null);
await rm(target, { recursive: true, force: true }).catch(() => null);
}
// ---------------------------------------------------------------- configuration
/**
* Home Assistant's configuration for one fixture house.
*
* `demo:` is the integration the home-bridge tests already use: it produces a
* realistic mix of lights, covers, locks, climate and sensors that changes on
* its own, which is what makes the state-burst measurements honest. The extra
* helper entities exist only on the big house, and they are the ones the load
* harness drives when it needs a controlled update rate.
*/
function configurationYaml({ big }) {
const lines = [
'# Written by scripts/home-fleet.mjs. This is a load fixture, not a home.',
'default_config:',
'demo:',
'logger:',
' default: warning',
'http:',
' server_port: 8123',
];
if (!big) return `${lines.join('\n')}\n`;
const booleans = [];
const numbers = [];
const texts = [];
const per = Math.ceil(BIG_HOUSE_ENTITIES / 3);
for (let i = 0; i < per; i++) {
booleans.push(` load_switch_${i}:\n name: Load Switch ${i}`);
numbers.push(` load_level_${i}:\n name: Load Level ${i}\n min: 0\n max: 100\n step: 1\n mode: box`);
texts.push(` load_note_${i}:\n name: Load Note ${i}\n max: 60`);
}
lines.push('input_boolean:', ...booleans, 'input_number:', ...numbers, 'input_text:', ...texts);
return `${lines.join('\n')}\n`;
}
// ---------------------------------------------------------------- onboarding
async function waitForHttp(url, timeoutMs) {
const deadline = Date.now() + timeoutMs;
let lastError = 'no response';
while (Date.now() < deadline) {
try {
const res = await fetch(url, { redirect: 'manual' });
if (res.status < 500) return true;
lastError = `status ${res.status}`;
} catch (err) {
lastError = err.message;
}
await sleep(1000);
}
throw new Error(`${url} never came up within ${timeoutMs}ms (${lastError})`);
}
async function postJson(url, body, token) {
const res = await fetch(url, {
method: 'POST',
headers: {
'content-type': 'application/json',
...(token ? { authorization: `Bearer ${token}` } : {}),
},
body: JSON.stringify(body),
});
const text = await res.text();
if (!res.ok) throw new Error(`POST ${url} -> ${res.status} ${text.slice(0, 200)}`);
return text ? JSON.parse(text) : null;
}
/**
* Walk Home Assistant's real onboarding API, exactly as the browser does, and
* come back with an access token. There is no shortcut here and there should
* not be: an instance that has not been onboarded rejects every other call.
*/
async function onboard(baseUrl, username) {
const clientId = `${baseUrl}/`;
const { auth_code: code } = await postJson(`${baseUrl}/api/onboarding/users`, {
client_id: clientId,
name: 'Load Harness Owner',
username,
password: PASSWORD,
language: 'en',
});
const form = new URLSearchParams({ grant_type: 'authorization_code', code, client_id: clientId });
const res = await fetch(`${baseUrl}/auth/token`, {
method: 'POST',
headers: { 'content-type': 'application/x-www-form-urlencoded' },
body: form,
});
if (!res.ok) throw new Error(`token exchange -> ${res.status} ${await res.text()}`);
const { access_token: accessToken } = await res.json();
await postJson(
`${baseUrl}/api/onboarding/core_config`,
{ client_id: clientId },
accessToken,
).catch(() => null);
await postJson(`${baseUrl}/api/onboarding/analytics`, {}, accessToken).catch(() => null);
await postJson(`${baseUrl}/api/onboarding/integration`, { client_id: clientId, redirect_uri: clientId }, accessToken).catch(() => null);
return accessToken;
}
// ---------------------------------------------------------------- websocket work
/**
* A minimal authenticated WebSocket session against one instance.
*
* home-assistant-js-websocket is the client the product uses, but it is built to
* hold a connection open and reconnect forever, which is the wrong shape for a
* three-message provisioning errand. This is the errand-sized version and it is
* used for exactly two things: minting the long-lived token and seeding the area
* registry.
*/
async function wsSession(baseUrl, token, work) {
const wsUrl = `${baseUrl.replace(/^http/, 'ws')}/api/websocket`;
const socket = new WebSocket(wsUrl);
const pending = new Map();
let id = 1;
const ready = new Promise((resolve, reject) => {
socket.on('error', reject);
socket.on('close', () => reject(new Error('socket closed before auth completed')));
socket.on('message', (raw) => {
const msg = JSON.parse(raw.toString());
if (msg.type === 'auth_required') {
socket.send(JSON.stringify({ type: 'auth', access_token: token }));
return;
}
if (msg.type === 'auth_ok') {
resolve();
return;
}
if (msg.type === 'auth_invalid') {
reject(new Error(`auth rejected: ${msg.message}`));
return;
}
const waiter = pending.get(msg.id);
if (!waiter) return;
pending.delete(msg.id);
if (msg.success === false) waiter.reject(new Error(msg.error?.message || 'command failed'));
else waiter.resolve(msg.result);
});
});
await ready;
const send = (payload) =>
new Promise((resolve, reject) => {
const messageId = id++;
pending.set(messageId, { resolve, reject });
socket.send(JSON.stringify({ ...payload, id: messageId }));
});
try {
return await work(send);
} finally {
socket.close();
}
}
/**
* Home Assistant's demo integration ships entities but no areas, and the room
* graph the 3D scene renders is built from the area registry. A fixture house
* with zero areas would understate the graph rebuild cost, so every house in the
* fleet gets a real floor and real areas through the real registry API.
*/
const FLOORS = [
{ name: 'Ground floor', areas: ['Kitchen', 'Living Room', 'Hallway', 'Garage'] },
{ name: 'Upstairs', areas: ['Bedroom', 'Bathroom', 'Study'] },
];
async function seedRegistry(send) {
const areas = [];
for (const floor of FLOORS) {
let floorId = null;
try {
const created = await send({ type: 'config/floor_registry/create', name: floor.name });
floorId = created?.floor_id ?? null;
} catch {
// Instances older than the floor registry are still valid fixtures; the
// areas below simply land unassigned, which the graph already handles.
}
for (const name of floor.areas) {
try {
const area = await send({ type: 'config/area_registry/create', name, ...(floorId ? { floor_id: floorId } : {}) });
areas.push(area);
} catch {
// A duplicate name on a re-run is not a failure.
}
}
}
// Spread the house's entities across those areas, so the graph has real rooms
// with real rollups rather than one giant unassigned bucket.
const entities = await send({ type: 'config/entity_registry/list' });
const assignable = entities.filter((e) => !e.area_id);
let assigned = 0;
for (let i = 0; i < assignable.length && areas.length; i++) {
const area = areas[i % areas.length];
try {
await send({ type: 'config/entity_registry/update', entity_id: assignable[i].entity_id, area_id: area.area_id });
assigned++;
} catch {
// Some entities are not registry entries and cannot carry an area.
}
}
return { floors: FLOORS.length, areas: areas.length, entitiesAssigned: assigned };
}
async function mintLongLivedToken(send, clientName) {
return send({ type: 'auth/long_lived_access_token', client_name: clientName, lifespan: 3650 });
}
// ---------------------------------------------------------------- latency shim
/**
* A TCP proxy that delays every byte in both directions by a fixed amount.
*
* Chaos scenario 6 needs a genuinely slow house, and slowing one is the only
* honest way to prove the fast one beside it is unaffected. Delaying at the
* socket rather than inside Home Assistant means the slowness looks exactly like
* a distant house on a bad link, which is the real-world failure being modelled.
*/
export function startLatencyShim({ listenPort, targetPort, delayMs, targetHost = '127.0.0.1' }) {
const server = createServer((client) => {
const upstream = netConnect(targetPort, targetHost);
const pipeDelayed = (from, to) => {
from.on('data', (chunk) => {
setTimeout(() => {
if (!to.destroyed) to.write(chunk);
}, delayMs);
});
from.on('close', () => setTimeout(() => to.destroy(), delayMs + 50));
from.on('error', () => to.destroy());
};
pipeDelayed(client, upstream);
pipeDelayed(upstream, client);
});
return new Promise((resolve, reject) => {
server.once('error', reject);
server.listen(listenPort, '127.0.0.1', () => resolve(server));
});
}
// ---------------------------------------------------------------- fleet lifecycle
async function listContainers() {
const out = await docker('ps', '-a', '--filter', `name=${NAME_PREFIX}`, '--format', '{{.Names}}\t{{.Status}}');
return out
.split('\n')
.filter(Boolean)
.map((line) => {
const [name, status] = line.split('\t');
return { name, status };
});
}
async function startHouse({ index, big }) {
const name = `${NAME_PREFIX}${index}`;
const port = BASE_PORT + index;
const configDir = path.join(CONFIG_ROOT, String(index));
await docker('rm', '-f', name).catch(() => null);
await removeAsRoot(configDir);
await mkdir(configDir, { recursive: true });
await writeFile(path.join(configDir, 'configuration.yaml'), configurationYaml({ big }));
await writeFile(path.join(configDir, 'automations.yaml'), '[]\n');
await docker(
'run', '-d',
'--name', name,
'-p', `127.0.0.1:${port}:8123`,
'-e', 'TZ=UTC',
'-v', `${configDir}:/config`,
IMAGE,
);
const baseUrl = `http://127.0.0.1:${port}`;
const startedAt = Date.now();
await waitForHttp(`${baseUrl}/`, big ? 300_000 : 180_000);
const bootMs = Date.now() - startedAt;
const accessToken = await onboard(baseUrl, `owner${index}`);
const registry = await wsSession(baseUrl, accessToken, seedRegistry);
const token = await wsSession(baseUrl, accessToken, (send) => mintLongLivedToken(send, `three.ws load harness ${index}`));
const states = await fetch(`${baseUrl}/api/states`, { headers: { authorization: `Bearer ${token}` } }).then((r) => r.json());
return {
index,
name,
baseUrl,
port,
token,
big: Boolean(big),
bootMs,
entityCount: states.length,
registry,
};
}
async function up({ homes, big, slow }) {
await mkdir(path.dirname(MANIFEST), { recursive: true });
console.log(`starting ${homes} Home Assistant container(s) (${big} large), image ${IMAGE}`);
// Home Assistant's first boot is CPU heavy and largely serial inside the
// container, so starting them in one wave is faster than in sequence but a
// full parallel storm on a 16 core box starves each one. Four at a time is
// the measured sweet spot on this machine.
const specs = Array.from({ length: homes }, (_, i) => ({ index: i, big: i < big }));
const houses = [];
const WAVE = 4;
for (let i = 0; i < specs.length; i += WAVE) {
const wave = specs.slice(i, i + WAVE);
const settled = await Promise.all(
wave.map((spec) =>
startHouse(spec).then(
(house) => ({ ok: true, house }),
(error) => ({ ok: false, index: spec.index, error: error.message }),
),
),
);
for (const result of settled) {
if (result.ok) {
houses.push(result.house);
console.log(` up ${result.house.name} ${result.house.baseUrl} ${result.house.entityCount} entities boot ${result.house.bootMs}ms`);
} else {
console.error(` FAIL house ${result.index}: ${result.error}`);
}
}
}
if (!houses.length) throw new Error('no house came up; nothing to measure');
const manifest = {
createdAt: new Date().toISOString(),
image: IMAGE,
slowShim: slow ? { listenPort: BASE_PORT + 900, delayMs: 2000, targetIndex: houses[houses.length - 1].index } : null,
houses,
};
await writeFile(MANIFEST, `${JSON.stringify(manifest, null, 2)}\n`);
console.log(`\nmanifest: ${path.relative(ROOT, MANIFEST)} (${houses.length} houses)`);
return manifest;
}
async function down() {
const containers = await listContainers();
for (const { name } of containers) {
await docker('rm', '-f', name).catch(() => null);
console.log(` removed ${name}`);
}
await removeAsRoot(CONFIG_ROOT);
await rm(MANIFEST, { force: true });
console.log(containers.length ? `\n${containers.length} container(s) removed` : 'nothing running');
}
/**
* Rebuild one house in place and re-record it in the manifest.
*
* A fleet is not immutable: a chaos run that revokes a credential, or a
* container that dies badly, leaves one house unusable while the other eleven
* are fine. Rebuilding the whole fleet to fix one of them costs minutes, so this
* replaces exactly the house named and leaves the rest alone.
*/
async function repair({ index, big }) {
const manifest = await readFleet();
const existing = manifest.houses.find((h) => h.index === index);
if (!existing) throw new Error(`no house ${index} in the manifest`);
console.log(`rebuilding house ${index} (${existing.name})`);
const rebuilt = await startHouse({ index, big: big ?? existing.big });
manifest.houses = manifest.houses.map((h) => (h.index === index ? rebuilt : h));
manifest.repairedAt = new Date().toISOString();
await writeFile(MANIFEST, `${JSON.stringify(manifest, null, 2)}\n`);
console.log(` up ${rebuilt.name} ${rebuilt.baseUrl} ${rebuilt.entityCount} entities boot ${rebuilt.bootMs}ms`);
return rebuilt;
}
async function status() {
const containers = await listContainers();
if (!containers.length) {
console.log('no fleet containers');
return;
}
for (const { name, status: state } of containers) console.log(` ${name}\t${state}`);
const manifest = await readFile(MANIFEST, 'utf8').then(JSON.parse).catch(() => null);
if (manifest) {
console.log(`\nmanifest from ${manifest.createdAt}: ${manifest.houses.length} houses, ${manifest.houses.reduce((n, h) => n + h.entityCount, 0)} entities total`);
}
}
export async function readFleet() {
const raw = await readFile(MANIFEST, 'utf8').catch(() => null);
if (!raw) throw new Error(`no fleet manifest at ${path.relative(ROOT, MANIFEST)}. Run: node scripts/home-fleet.mjs up --homes 10`);
return JSON.parse(raw);
}
export { MANIFEST, NAME_PREFIX, BASE_PORT };
// ---------------------------------------------------------------- cli
function parseArgs(argv) {
const out = { _: [] };
for (let i = 0; i < argv.length; i++) {
const arg = argv[i];
if (arg.startsWith('--')) out[arg.slice(2)] = argv[i + 1]?.startsWith('--') || argv[i + 1] === undefined ? true : argv[++i];
else out._.push(arg);
}
return out;
}
const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
if (isMain) {
const args = parseArgs(process.argv.slice(2));
const command = args._[0] || 'status';
const run = {
up: () => up({ homes: Number(args.homes || 10), big: Number(args.big || 0), slow: Boolean(args.slow) }),
repair: () => repair({ index: Number(args.index), big: args.big === undefined ? undefined : Boolean(args.big) }),
down,
status,
}[command];
if (!run) {
console.error(`unknown command "${command}". Use: up | repair --index N | down | status`);
process.exit(2);
}
run().then(
() => process.exit(0),
(err) => {
console.error(err.stack || err.message);
process.exit(1);
},
);
}