Tin
Reference · Servers

On this page

Servers

The server declaration: routes, Request and Response, request taint and its sinks, grants, agent endpoints over HTTP, SSE, WebSocket and MCP, limits and the handler contract.

The server declaration

server Api grants [net.listen(8080), model] {
  agents: [Support]                  // optional: which agents get endpoints (default: all)
  get "/" (req) => "hello"
  get "/hello/:name" (req) => "hi {req.params.getOr("name", "")}"
  post "/ask" (req) => Support(req.body)
  ws "/voice" = Concierge            // a WebSocket to an agent (text or voice)
}
  • Routes: get, post, put, patch, delete and ws. They are words only inside a server block, not keywords.
  • A path starts with /; :name is a parameter (URL-decoded, never empty). Routes with more fixed segments match first, then the order they are written. HEAD is answered by the GET route. A path that matches with another method answers 405 with Allow.
  • (req) is the request, typed Request; leave it out when the handler doesn't read it. A return type is optional: get "/n" (req): Result<int, string> { ... }.
  • One server per program. A program with agents and no server has an implicit one: every agent gets its endpoints, no routes, and the grants are what the agents use.
  • /agents/..., /mcp, /healthz and /.well-known/... are reserved paths.

Request and Response

Both types exist only in a program that has a server (so other programs may name their own types Request and Response).

type Request = {
  method: string,                 // GET, POST, PUT, PATCH or DELETE
  path: string,                   // without the query string
  params: Map<string, string>,    // the :name parts
  query: Map<string, string>,     // ?k=v (the last one wins)
  headers: Map<string, string>,   // names in lowercase
  body: string,                   // "" when there is none
}
type Response = { status: int, headers: Map<string, string>, body: string }
fn respond(status: int, body: string): Response
fn encodeUri(s: string): string   // %XX everything but A-Z a-z 0-9 - . _ ~
fn escapeHtml(s: string): string  // & < > " ' as entities

What a handler returns

Return typeAnswer
string200, text/plain; charset=utf-8
Responseits status, headers and body (text/plain unless a content-type is set; no body for 204 and 304)
Result<T, E>Ok: 200 with the value as JSON. Err: 400 with {"error": ...}
anything else200 JSON, encoded like a tool result
a panic500 {"error"}; the instance is thrown away and the panic goes to the log

Request taint

Everything in a Request comes from the client. The compiler tracks it through locals, function calls (with summaries to a fixpoint), arrays, maps, sets, loops, struct fields and closures' arguments. It may not reach a sink unless it went through what that sink accepts. The check over-approximates: a value computed from request input is request input (a length of the body is too), so a false alarm is possible and a missed one is a bug.

SinkCleans itError says
an extern fn (JavaScript, Python, MCP: SQL, a shell, a file)parseInt, parseFloat; a call that returns a number, bool or char (s.contains(..), m.size()); approve of a guarded tool fnthe request's input reaches extern fn name
the URL of fetchthe above, and encodeUrithe request's input reaches the URL of fetch
a response header: Response { headers: … }, r.headers.set, r.headers[k] = v, r.headers = …, through helpersthe above, and encodeUrithe request's input reaches a response header

escapeHtml cleans for none of these: it protects HTML only, and ; or $(..) pass through it unchanged. SQL and shells have no sanitizer on purpose: parse the value, match it against text the program writes, or put the call behind approve. The response body is not a sink; it goes back to the client who sent it. A model's reply keeps its own taint (it may not reach an extern without approval), with or without a server. Header values with CR or LF are also refused at run time (500).

Grants

grants [...] is a ceiling, checked against what the routes and the exposed agents reach. A missing grant is an error naming the route or agent, with a fix that adds it. A grant nothing uses is allowed.

GrantAllows
net.listen(port)serving at all (required); port is the default, PORT or --port wins
net.fetchfetch to other servers
modelcalling agents and voice agents
envreading environment variables
js, py, mcpextern fns from JavaScript, Python, MCP servers
spawntasks

Always allowed: print (to the log), the clock and random numbers. mic(), speaker() and input() are errors in a server.

Agent endpoints

EndpointWhat it does
POST /agents/<Name>the body (text, or JSON {"prompt": "..."}) is the question. JSON answer {text, turns, tokens}; with Accept: text/event-stream, SSE: text, tool, tool_result events as the loop runs, then done or error
GET /agents/<Name>name, description (from ///), tools and endpoints
/agents/<Name>/wsa WebSocket (below)
POST /mcpMCP over Streamable HTTP (request/response): every text agent is a tool with a prompt argument
GET /, GET /healthzan index of routes and agents (when no route claims /), and {"ok": true}

Guarded tools are denied on a server: no one is there to approve them.

WebSocket protocol

Text agent. One socket is one conversation: the agent remembers earlier messages until the socket closes. Send plain text, {"prompt": "..."} or {"type": "prompt", "text": "..."}. The server answers with the SSE events as JSON messages ({"type": "text", ...}), then {"type": "done", "text", "turns", "tokens"} or {"type": "error", "message"}.

Voice agent. The server sends {"type": "hello", "agent", "inputRate"}. Send binary messages of PCM16 mono little-endian audio at ?rate= (default 16000, from 8000 to 48000), then {"type": "end"}. The server sends {"type": "format", "rate"} before its first audio, the agent's speech as binary PCM16, {"type": "clear"} when the user talks over it (drop queued audio), and {"type": "done", "transcript"}, then closes.

WebSockets work under tin serve, in the Node entry (containers: Cloud Run, Azure Container Apps), on Cloudflare Workers and on tin.ad. Vercel functions, Lambda and Pages can't hold a socket, so a ws route is a compile error for those targets.

Isolation and concurrency

Every request gets a fresh instance of the compiled module (the module itself is compiled once). Nothing in Tin memory outlives a request, there are no globals to share, and a panic or timeout throws away only that instance. A WebSocket keeps one instance for its lifetime. Requests run concurrently on one event loop; an instance pauses only at a model call, fetch, sleep or an extern that returns a promise. CPU-bound handlers don't run in parallel within one process.

Measured on an M-series MacBook (Node 26, createHandler in-process, no network, 2026-11-16):

LoadThroughputp50p99
GET /hello/:n, one at a time9,400 req/s0.05 ms0.33 ms
GET /hello/:n, 64 at once13,500 req/s3.1 ms17 ms
POST /agents/Support (mock model), 64 at once12,800 req/s3.3 ms17 ms

Memory stayed flat: 20,000 more requests moved the process from 203 MB to 208 MB. A real model call takes hundreds of milliseconds, so in practice the limit is the provider, not the server.

Limits

LimitDefaultOver it
request body1 MB413
time per request (or per WebSocket message)120 s504
requests in flight64503 with Retry-After
audio on one voice socket64 MBerror, input ends

The handler contract

A server compiles to one web-standard handler; each platform adds a thin adapter. From tin build app.tin --target server (or src/serve.ts):

createHandler({ wasm: WebAssembly.Module, env?, limits?, log?, models?, voiceModels? }) → {
  fetch(req: Request, env?, ctx?): Promise<Response>
  wants(req: Request): boolean                   // a WebSocket upgrade this handler serves?
  socket(conn: TinSocket, req: Request, env?): void
}
TinSocket = { send(string | Uint8Array), close(code?, reason?), onmessage?(string | ArrayBuffer), onclose?() }

env passed to fetch (Workers secrets) wins over opts.env. Workers can't compile WebAssembly from bytes at run time, so every entry passes a compiled module.

What does not work yet

  • No raw TCP, and no server-initiated MCP stream (GET /mcp answers 405).
  • A voice WebSocket has no live heard/said events and no text say or interrupt messages yet; the transcript comes at the end.
  • Taint does not follow values through a closure's captured variables or a task's result (the same limit as model taint).
  • int is 32-bit, so a JSON number over 2,147,483,647 in a request needs float.