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
/**
* The three.ws home relay.
*
* A house that only exists on a LAN cannot be reached from Cloud Run, so the
* house dials out instead: the three.ws integration inside Home Assistant opens
* one outbound WebSocket to this service and keeps it. The platform then asks
* this service to open a session over that socket. Nothing listens on the
* user's network, no port is forwarded, and no inbound firewall rule exists.
*
* This service is deliberately small and deliberately dumb:
*
* * It holds no database. Ownership is proved by the signature on the install
* token the house presents (`token.js`), so the connect path never queries
* anything.
* * It holds no Home Assistant credential, ever. Authentication happens
* locally inside the house and never crosses this process.
* * It forwards only the message types in `protocol.js`, in the direction
* that protocol permits, and the integration enforces the same list again
* at the far end so that compromising this service does not compromise a
* house.
*
* Read `docs/home-relay-threat-model.md` before changing anything here.
*/
import { createServer } from 'node:http';
import { randomBytes } from 'node:crypto';
import { WebSocketServer } from 'ws';
import { CODE, FRAME, LIMITS, checkInbound, checkOutbound, decodeFrame, encodeFrame, frames, negotiate } from './protocol.js';
import { constantTimeEquals, verifyInstallToken } from './token.js';
const SERVICE_VERSION = '1.0.0';
/**
* A token bucket. Used per install for both frame rate and actuation rate,
* because a bug in an integration must not be able to flood a house and a
* compromised platform caller must not be able to hammer a lock.
*/
class Bucket {
constructor(capacity, refillPerSecond) {
this.capacity = capacity;
this.refillPerSecond = refillPerSecond;
this.tokens = capacity;
this.last = Date.now();
}
take(now = Date.now()) {
const elapsed = Math.max(0, now - this.last) / 1000;
this.last = now;
this.tokens = Math.min(this.capacity, this.tokens + elapsed * this.refillPerSecond);
if (this.tokens < 1) return false;
this.tokens -= 1;
return true;
}
}
/** One dialled-in house. */
class Install {
constructor(relayId, socket, claims, agentInfo) {
this.relayId = relayId;
this.socket = socket;
this.claims = claims;
this.agent = agentInfo;
this.connectedAt = Date.now();
this.sessions = new Map();
this.frameBucket = new Bucket(LIMITS.outboundFramesPerSecond, LIMITS.outboundFramesPerSecond);
this.callBucket = new Bucket(LIMITS.serviceCallsPerMinute, LIMITS.serviceCallsPerMinute / 60);
this.alive = true;
this.counters = { framesIn: 0, framesOut: 0, denied: 0, sessions: 0 };
}
send(frame) {
if (this.socket.readyState !== this.socket.OPEN) return false;
this.socket.send(encodeFrame(frame));
this.counters.framesOut += 1;
return true;
}
}
export function createRelay(options = {}) {
const signingKey = options.signingKey || process.env.HOME_RELAY_SIGNING_KEY;
const serviceToken = options.serviceToken || process.env.HOME_RELAY_SERVICE_TOKEN;
if (!signingKey || signingKey.length < 32) throw new Error('HOME_RELAY_SIGNING_KEY must be set to at least 32 characters.');
if (!serviceToken || serviceToken.length < 32) throw new Error('HOME_RELAY_SERVICE_TOKEN must be set to at least 32 characters.');
const log = options.log || ((event, fields) => console.log(JSON.stringify({ event, ...fields })));
/** relayId to Install. One socket per house: a second dial-in replaces the first. */
const installs = new Map();
/** relayId to the epoch ms it was revoked, so a race cannot re-register it. */
const revoked = new Map();
const startedAt = Date.now();
const server = createServer((req, res) => handleHttp(req, res));
const agentWss = new WebSocketServer({ noServer: true, maxPayload: LIMITS.maxFrameBytes });
const bridgeWss = new WebSocketServer({ noServer: true, maxPayload: LIMITS.maxFrameBytes });
server.on('upgrade', (req, socket, head) => {
let url;
try {
url = new URL(req.url, 'http://relay.invalid');
} catch {
return refuseUpgrade(socket, 400, 'Bad request');
}
if (url.pathname === '/v1/agent') {
const auth = bearer(req);
const verdict = verifyInstallToken(auth, signingKey);
if (!verdict.ok) {
log('agent.rejected', { reason: verdict.reason });
return refuseUpgrade(socket, 401, 'Unauthorized');
}
if (revoked.has(verdict.claims.relayId)) {
log('agent.rejected', { relayId: verdict.claims.relayId, reason: 'revoked' });
return refuseUpgrade(socket, 403, 'Revoked');
}
return agentWss.handleUpgrade(req, socket, head, (ws) => onAgent(ws, verdict.claims));
}
if (url.pathname === '/v1/bridge') {
if (!constantTimeEquals(bearer(req), serviceToken)) {
log('bridge.rejected', { reason: 'bad service token' });
return refuseUpgrade(socket, 401, 'Unauthorized');
}
const relayId = url.searchParams.get('relay_id') || '';
return bridgeWss.handleUpgrade(req, socket, head, (ws) => onBridge(ws, relayId));
}
return refuseUpgrade(socket, 404, 'Not found');
});
// ---------------------------------------------------------------- the house
function onAgent(ws, claims) {
const { relayId } = claims;
let install = null;
let helloTimer = setTimeout(() => {
if (!install) {
ws.send(encodeFrame(frames.helloErr(CODE.MALFORMED, 'No hello frame within 10 seconds.')));
ws.close(4000, CODE.MALFORMED);
}
}, 10_000);
ws.on('message', (raw) => {
const decoded = decodeFrame(raw);
if (!decoded.ok) {
log('agent.malformed', { relayId, reason: decoded.message });
ws.close(4000, decoded.code);
return;
}
const frame = decoded.frame;
if (!install) {
if (frame.t !== FRAME.HELLO) {
ws.send(encodeFrame(frames.helloErr(CODE.MALFORMED, 'The first frame must be hello.')));
ws.close(4000, CODE.MALFORMED);
return;
}
const agreed = negotiate(frame.protocol);
if (!agreed.ok) {
log('agent.protocol', { relayId, code: agreed.code });
ws.send(encodeFrame(frames.helloErr(agreed.code, agreed.message)));
ws.close(4001, agreed.code);
return;
}
if (revoked.has(relayId)) {
ws.send(encodeFrame(frames.helloErr(CODE.REVOKED, 'This home was disconnected in three.ws. Remove and re-add the integration to pair it again.')));
ws.close(4003, CODE.REVOKED);
return;
}
clearTimeout(helloTimer);
helloTimer = null;
// One house, one socket. A stale socket from a crashed container
// would otherwise shadow the live one forever.
const previous = installs.get(relayId);
if (previous && previous.socket !== ws) {
closeInstall(previous, CODE.GOING_AWAY, 'Replaced by a newer connection from this home.');
}
install = new Install(relayId, ws, claims, sanitizeAgentInfo(frame.agent));
installs.set(relayId, install);
ws.send(encodeFrame(frames.helloOk(relayId, { version: SERVICE_VERSION })));
log('agent.online', { relayId, agent: install.agent, protocol: agreed.protocol });
return;
}
install.counters.framesIn += 1;
routeFromAgent(install, frame);
});
ws.on('pong', () => {
if (install) install.alive = true;
});
ws.on('close', () => {
if (helloTimer) clearTimeout(helloTimer);
if (install && installs.get(relayId) === install) {
installs.delete(relayId);
for (const session of install.sessions.values()) {
session.bridge.send(encodeFrame(frames.sessionClose(session.sid, CODE.AGENT_OFFLINE, 'The three.ws integration in this home went offline.')));
session.bridge.close(1000, CODE.AGENT_OFFLINE);
}
install.sessions.clear();
log('agent.offline', { relayId, uptimeMs: Date.now() - install.connectedAt, counters: install.counters });
}
});
ws.on('error', (err) => log('agent.error', { relayId, message: err?.message }));
}
function routeFromAgent(install, frame) {
if (frame.t === FRAME.PONG || frame.t === FRAME.PING) {
if (frame.t === FRAME.PING) install.send(frames.pong(frame.ts));
return;
}
const session = install.sessions.get(frame.sid);
if (!session) return; // A reply for a session the platform already dropped.
if (frame.t === FRAME.SESSION_READY) {
session.ready = true;
session.bridge.send(encodeFrame(frames.sessionReady(session.sid, String(frame.haVersion || ''))));
return;
}
if (frame.t === FRAME.SESSION_CLOSE) {
session.bridge.send(encodeFrame(frames.sessionClose(session.sid, String(frame.code || CODE.OK), String(frame.reason || ''))));
session.bridge.close(1000, String(frame.code || CODE.OK));
return;
}
if (frame.t === FRAME.HA) {
const verdict = checkInbound(frame.msg);
if (!verdict.allowed) {
install.counters.denied += 1;
log('relay.denied', { relayId: install.relayId, direction: 'inbound', code: verdict.code, reason: verdict.reason });
return;
}
session.bridge.send(encodeFrame(frames.ha(session.sid, frame.msg)));
}
}
// ------------------------------------------------------------- the platform
function onBridge(ws, relayId) {
const install = installs.get(relayId);
if (!relayId || !install) {
ws.send(encodeFrame(frames.sessionClose('pending', CODE.AGENT_OFFLINE, 'No three.ws integration is connected for this home right now.')));
ws.close(1000, CODE.AGENT_OFFLINE);
return;
}
if (install.sessions.size >= LIMITS.maxSessionsPerInstall) {
ws.send(encodeFrame(frames.sessionClose('pending', CODE.TOO_MANY_SESSIONS, `This home already has ${install.sessions.size} open sessions.`)));
ws.close(1000, CODE.TOO_MANY_SESSIONS);
return;
}
const sid = `s_${randomBytes(9).toString('base64url')}`;
const session = { sid, bridge: ws, install, ready: false, openedAt: Date.now() };
install.sessions.set(sid, session);
install.counters.sessions += 1;
install.send(frames.sessionOpen(sid));
log('session.open', { relayId, sid });
ws.on('message', (raw) => {
const decoded = decodeFrame(raw);
if (!decoded.ok) {
ws.send(encodeFrame(frames.sessionClose(sid, decoded.code, decoded.message)));
ws.close(4000, decoded.code);
return;
}
const frame = decoded.frame;
if (frame.t === FRAME.SESSION_CLOSE) {
ws.close(1000, CODE.OK);
return;
}
if (frame.t !== FRAME.HA) return;
if (!install.frameBucket.take()) {
install.counters.denied += 1;
log('relay.rate_limited', { relayId, kind: 'frames' });
replyRefusal(ws, sid, frame.msg, CODE.RATE_LIMITED, 'Too many requests into this home. Slow down.');
return;
}
const verdict = checkOutbound(frame.msg);
if (!verdict.allowed) {
install.counters.denied += 1;
log('relay.denied', { relayId, direction: 'outbound', code: verdict.code, reason: verdict.reason, type: typeof frame.msg?.type === 'string' ? frame.msg.type.slice(0, 64) : null });
replyRefusal(ws, sid, frame.msg, verdict.code, verdict.reason);
return;
}
if (frame.msg.type === 'call_service' && !install.callBucket.take()) {
install.counters.denied += 1;
log('relay.rate_limited', { relayId, kind: 'call_service' });
replyRefusal(ws, sid, frame.msg, CODE.RATE_LIMITED, 'Too many service calls into this home in the last minute.');
return;
}
install.send(frames.ha(sid, frame.msg));
});
ws.on('close', () => {
if (install.sessions.get(sid) === session) {
install.sessions.delete(sid);
install.send(frames.sessionClose(sid, CODE.OK, 'The platform closed this session.'));
log('session.close', { relayId, sid, ms: Date.now() - session.openedAt });
}
});
ws.on('error', (err) => log('bridge.error', { relayId, sid, message: err?.message }));
}
/**
* A refused frame gets a Home Assistant shaped error result rather than a
* dropped connection, so the client's own promise rejects with a real
* message instead of hanging until its timeout. The session survives: one
* bad call is not a reason to tear down a live house.
*/
function replyRefusal(ws, sid, msg, code, reason) {
const id = Number.isInteger(msg?.id) ? msg.id : null;
if (id === null) return;
ws.send(encodeFrame(frames.ha(sid, { id, type: 'result', success: false, error: { code, message: reason } })));
}
// ------------------------------------------------------------------- admin
function handleHttp(req, res) {
const url = new URL(req.url || '/', 'http://relay.invalid');
if (req.method === 'GET' && (url.pathname === '/healthz' || url.pathname === '/')) {
return sendJson(res, 200, {
ok: true,
service: 'home-relay',
version: SERVICE_VERSION,
uptimeSeconds: Math.round((Date.now() - startedAt) / 1000),
installs: installs.size,
sessions: [...installs.values()].reduce((n, i) => n + i.sessions.size, 0),
});
}
if (!constantTimeEquals(bearer(req), serviceToken)) return sendJson(res, 401, { error: 'unauthorized' });
if (req.method === 'GET' && url.pathname === '/v1/status') {
const relayId = url.searchParams.get('relay_id');
if (relayId) {
const install = installs.get(relayId);
return sendJson(res, 200, { relayId, online: Boolean(install), ...(install ? describeInstall(install) : { revokedAt: revoked.get(relayId) || null }) });
}
return sendJson(res, 200, { installs: [...installs.values()].map((i) => ({ relayId: i.relayId, ...describeInstall(i) })) });
}
if (req.method === 'POST' && url.pathname === '/v1/revoke') {
return readJson(req, (body) => {
const relayId = body?.relayId;
if (typeof relayId !== 'string' || !relayId) return sendJson(res, 400, { error: 'relayId is required' });
revoked.set(relayId, Date.now());
const install = installs.get(relayId);
if (install) closeInstall(install, CODE.REVOKED, 'This home was disconnected in three.ws.');
log('relay.revoked', { relayId, wasOnline: Boolean(install) });
return sendJson(res, 200, { relayId, revoked: true, wasOnline: Boolean(install) });
}, res);
}
if (req.method === 'POST' && url.pathname === '/v1/unrevoke') {
return readJson(req, (body) => {
const relayId = body?.relayId;
if (typeof relayId !== 'string' || !relayId) return sendJson(res, 400, { error: 'relayId is required' });
const had = revoked.delete(relayId);
log('relay.unrevoked', { relayId, had });
return sendJson(res, 200, { relayId, revoked: false });
}, res);
}
return sendJson(res, 404, { error: 'not found' });
}
function describeInstall(install) {
return {
agent: install.agent,
connectedAt: new Date(install.connectedAt).toISOString(),
sessions: install.sessions.size,
counters: { ...install.counters },
};
}
function closeInstall(install, code, reason) {
for (const session of install.sessions.values()) {
try {
session.bridge.send(encodeFrame(frames.sessionClose(session.sid, code, reason)));
session.bridge.close(1000, code);
} catch {
// A bridge socket that is already gone needs no further closing.
}
}
install.sessions.clear();
if (installs.get(install.relayId) === install) installs.delete(install.relayId);
try {
install.socket.send(encodeFrame(frames.sessionClose('all', code, reason)));
install.socket.close(4003, code);
} catch {
// Same: the socket may already be dead, which is the outcome we wanted.
}
}
// --------------------------------------------------------------- heartbeat
const heartbeat = setInterval(() => {
for (const install of installs.values()) {
if (!install.alive) {
log('agent.timeout', { relayId: install.relayId });
install.socket.terminate();
continue;
}
install.alive = false;
try {
install.socket.ping();
} catch {
install.socket.terminate();
}
}
}, LIMITS.heartbeatMs);
heartbeat.unref?.();
return {
server,
installs,
revoked,
stats: () => ({
installs: installs.size,
sessions: [...installs.values()].reduce((n, i) => n + i.sessions.size, 0),
revoked: revoked.size,
}),
listen: (port, host = '0.0.0.0') => new Promise((resolve) => server.listen(port, host, () => resolve(server.address()))),
close: async () => {
clearInterval(heartbeat);
for (const install of [...installs.values()]) closeInstall(install, CODE.GOING_AWAY, 'The relay is shutting down.');
agentWss.close();
bridgeWss.close();
await new Promise((resolve) => server.close(resolve));
},
};
}
function sanitizeAgentInfo(agent) {
if (!agent || typeof agent !== 'object') return { name: 'unknown', version: 'unknown' };
const trim = (value, max) => (typeof value === 'string' ? value.slice(0, max) : 'unknown');
return { name: trim(agent.name, 64), version: trim(agent.version, 32), ha: trim(agent.ha, 32) };
}
function bearer(req) {
const header = req.headers?.authorization || '';
return header.startsWith('Bearer ') ? header.slice(7) : '';
}
function refuseUpgrade(socket, status, text) {
socket.write(`HTTP/1.1 ${status} ${text}\r\nConnection: close\r\n\r\n`);
socket.destroy();
}
function sendJson(res, status, body) {
const payload = JSON.stringify(body);
res.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) });
res.end(payload);
}
function readJson(req, onBody, res) {
const chunks = [];
let size = 0;
req.on('data', (chunk) => {
size += chunk.length;
if (size > 64 * 1024) {
req.destroy();
return;
}
chunks.push(chunk);
});
req.on('end', () => {
try {
onBody(JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}'));
} catch {
sendJson(res, 400, { error: 'body must be JSON' });
}
});
}