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
// GET /api/tty: stream a 3D agent into the caller's terminal.
//
// curl three.ws/tty
// curl three.ws/tty/<avatar-id>
// curl 'three.ws/tty?src=https://example.com/model.glb&frames=120'
//
// The whole point is that it needs nothing installed. No GPU on this side, no
// WebGL on the caller's side, no client at all beyond curl: the server runs the
// software rasterizer from @three-ws/tty (packages/tty-3d) and writes ANSI
// frames down a chunked response, pacing them so the response IS the animation.
//
// Why a stream rather than a rendered file: a GIF would need an encoder, a
// content type the terminal cannot show, and a download step. Frames of text
// arrive progressively and start animating before the model has even finished
// sending, which is the difference between a demo and a trick.
import { existsSync } from 'node:fs';
import { join } from 'node:path';
import { createRenderer, loadModel } from '../packages/tty-3d/src/index.js';
import { ansi, ColorMode } from '../packages/tty-3d/src/term.js';
import { getAvatar } from './_lib/avatars.js';
import { error, rateLimited, redirect, wantsHtmlNavigation, wrap } from './_lib/http.js';
import { fetchModel } from './_lib/fetch-model.js';
import { clientIp, limits } from './_lib/rate-limit.js';
import { assertSafePublicUrl, SsrfBlockedError } from './_lib/ssrf-guard.js';
export const maxDuration = 60;
// The signature model, used when the caller names nothing. It is the one GLB
// every deploy is guaranteed to ship, so `curl three.ws/tty` can never 404.
//
// Read off disk, NOT fetched from our own origin. Self-fetching looked simpler
// and was wrong twice over: it has to guess its own scheme from headers (which
// fails outright behind a proxy that does not set x-forwarded-proto, and failed
// immediately in local testing against https://localhost), and it spends a
// network round trip to read a file that is already in the image.
const DEFAULT_MODEL_CANDIDATES = ['dist/avatars/default.glb', 'public/avatars/default.glb'];
export function defaultModelPath(cwd = process.cwd()) {
for (const rel of DEFAULT_MODEL_CANDIDATES) {
const full = join(cwd, rel);
if (existsSync(full)) return full;
}
return null;
}
const MAX_MODEL_BYTES = 64 * 1024 * 1024;
const MAX_FRAMES = 600;
const MAX_SECONDS = 45;
const MIN_COLS = 20;
const MAX_COLS = 220;
const MIN_ROWS = 8;
const MAX_ROWS = 90;
const clampInt = (raw, min, max, fallback) => {
const n = Number.parseInt(raw, 10);
if (!Number.isFinite(n)) return fallback;
return Math.max(min, Math.min(max, n));
};
const clampFloat = (raw, min, max, fallback) => {
const n = Number.parseFloat(raw);
if (!Number.isFinite(n)) return fallback;
return Math.max(min, Math.min(max, n));
};
/**
* Terminals do not announce themselves, so colour depth is inferred from what
* curl passes through. A caller who knows better can always say `?color=`.
*/
export function colorModeFor(query, headers = {}) {
const asked = String(query.color ?? '').toLowerCase();
if (Object.values(ColorMode).includes(asked)) return asked;
// curl forwards neither COLORTERM nor TERM, so the safe default over the
// wire is 256 colour: universally supported by anything that renders escape
// sequences at all, and visibly better than the ASCII ramp.
if (String(headers['x-color'] ?? '').toLowerCase() === 'truecolor') return ColorMode.TRUECOLOR;
return ColorMode.ANSI256;
}
/** Resolve what to draw: an explicit GLB URL, an avatar id, or the default. */
export async function resolveSource(query) {
if (query.src) {
// Caller-supplied URLs are fetched by this server, so they are an SSRF
// vector like any other. Same guard the render endpoints use.
const safe = await assertSafePublicUrl(String(query.src));
return { url: safe.toString ? safe.toString() : String(query.src), label: 'model' };
}
const avatarId = query.avatar ? String(query.avatar) : '';
if (avatarId) {
const avatar = await getAvatar({ id: avatarId });
if (!avatar) return null;
// model_url is null for a private avatar, which is exactly the case that
// must not render: this endpoint is unauthenticated.
if (!avatar.model_url) return null;
return { url: avatar.model_url, label: avatar.name || 'avatar' };
}
const local = defaultModelPath();
if (!local) return null;
return { url: local, label: 'default agent' };
}
// Remote models are fetched by the pinned, per-hop validated fetcher (redirects
// handled manually, every hop resolved and connection-pinned), never by loadModel's
// own redirect-following fetch. Applies to src and to a stored avatar model_url.
async function loadSource(url) {
if (/^https?:\/\//i.test(url)) {
const { bytes } = await fetchModel(url, { maxBytes: MAX_MODEL_BYTES });
return loadModel(bytes);
}
return loadModel(url);
}
function banner(label, info, cols) {
const left = `three.ws ${label}`;
const right = `${info.triangles.toLocaleString('en-US')} tris${info.skinned ? ' rigged' : ''}`;
const gap = Math.max(1, cols - left.length - right.length);
return `${left}${' '.repeat(gap)}${right}`;
}
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
export default wrap(async function handler(req, res) {
const url = new URL(req.url, 'http://localhost');
const query = Object.fromEntries(url.searchParams);
// A browser that lands here would see escape codes as literal mojibake, so
// send it somewhere that explains the trick instead.
if (wantsHtmlNavigation(req) && !query.raw) {
const to = query.avatar ? `/tty?avatar=${encodeURIComponent(String(query.avatar))}` : '/tty';
return redirect(res, to, 302);
}
const rate = await limits.ttyIp(clientIp(req) || 'anon');
if (!rate.success) {
return rateLimited(res, rate, `Too many terminal renders. Limit: ${rate.limit} per 10m.`);
}
let source;
try {
source = await resolveSource(query);
} catch (err) {
if (err instanceof SsrfBlockedError) return error(res, 400, 'blocked_url', 'that model URL is not reachable');
throw err;
}
if (!source) return error(res, 404, 'not_found', 'no model to render');
const cols = clampInt(query.w ?? query.cols, MIN_COLS, MAX_COLS, 76);
const rows = clampInt(query.h ?? query.rows, MIN_ROWS, MAX_ROWS, 30);
const fps = clampInt(query.fps, 4, 30, 18);
const spin = clampFloat(query.spin, -4, 4, 0.9);
const frames = clampInt(query.frames, 1, Math.min(MAX_FRAMES, fps * MAX_SECONDS), fps * 8);
let model;
try {
model = await loadSource(source.url);
} catch (err) {
// Upstream detail (status, resolver verdicts) stays out of the response:
// it would turn this endpoint into an internal-network probe.
return error(res, 502, 'model_unavailable', 'could not read that model');
}
const renderer = createRenderer(model, {
width: cols,
height: rows,
mode: colorModeFor(query, req.headers),
animation: query.clip ?? undefined,
spin,
pitch: clampFloat(query.pitch, -1.4, 1.4, 0.08),
zoom: clampFloat(query.zoom, 0.3, 6, 1),
});
res.statusCode = 200;
res.setHeader('content-type', 'text/plain; charset=utf-8');
res.setHeader('cache-control', 'no-store');
// Nothing may buffer this: a proxy that waits for the body to finish turns a
// live animation into a wall of text delivered at the end.
res.setHeader('x-accel-buffering', 'no');
res.setHeader('x-content-type-options', 'nosniff');
if (typeof res.flushHeaders === 'function') res.flushHeaders();
const info = { triangles: model.triangleCount, skinned: model.skinned };
const single = frames === 1;
// A single frame can be asked for at any point in the clip, which is what
// makes `?frames=1&t=` a usable still-image API and not just a first frame.
const startTime = clampFloat(query.t ?? query.time, 0, 600, 0);
// A client that hangs up mid-animation (Ctrl-C on curl) must stop the render
// loop, not keep rasterizing frames into a dead socket for another 40s.
let aborted = false;
const stop = () => { aborted = true; };
req.on('aborted', stop);
res.on('close', stop);
if (!single) res.write(ansi.hideCursor + '\n'.repeat(rows + 1));
try {
for (let i = 0; i < frames && !aborted; i += 1) {
const time = startTime + i / fps;
const frame = renderer.frame(time);
const head = single ? '' : ansi.up(rows + 1);
res.write(`${head}${frame}\n${banner(source.label, info, cols)}\n`);
if (single) break;
await sleep(Math.round(1000 / fps));
}
} finally {
if (!aborted) {
if (!single) res.write(ansi.showCursor);
res.end();
}
}
});