Reference · Servers
- The language
- Agents and tools
- Model providers
- The Anthropic API
- Talking agents
- Standard library
- Glossary
- Package docs
- Telemetry
- Robots
- Servers
- Deploying
- tin.ad
- The tin command
- How it works
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,deleteandws. They are words only inside aserverblock, not keywords. - A path starts with
/;:nameis a parameter (URL-decoded, never empty). Routes with more fixed segments match first, then the order they are written.HEADis answered by theGETroute. A path that matches with another method answers 405 withAllow. (req)is the request, typedRequest; leave it out when the handler doesn't read it. A return type is optional:get "/n" (req): Result<int, string> { ... }.- One
serverper program. A program with agents and noserverhas an implicit one: every agent gets its endpoints, no routes, and the grants are what the agents use. /agents/...,/mcp,/healthzand/.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 type | Answer |
|---|---|
string | 200, text/plain; charset=utf-8 |
Response | its 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 else | 200 JSON, encoded like a tool result |
| a panic | 500 {"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.
| Sink | Cleans it | Error 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 fn | the request's input reaches extern fn name |
the URL of fetch | the above, and encodeUri | the request's input reaches the URL of fetch |
a response header: Response { headers: … }, r.headers.set, r.headers[k] = v, r.headers = …, through helpers | the above, and encodeUri | the 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.
| Grant | Allows |
|---|---|
net.listen(port) | serving at all (required); port is the default, PORT or --port wins |
net.fetch | fetch to other servers |
model | calling agents and voice agents |
env | reading environment variables |
js, py, mcp | extern fns from JavaScript, Python, MCP servers |
spawn | tasks |
Always allowed: print (to the log), the clock and random numbers. mic(),
speaker() and input() are errors in a server.
Agent endpoints
| Endpoint | What 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>/ws | a WebSocket (below) |
POST /mcp | MCP over Streamable HTTP (request/response): every text agent is a tool with a prompt argument |
GET /, GET /healthz | an 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):
| Load | Throughput | p50 | p99 |
|---|---|---|---|
GET /hello/:n, one at a time | 9,400 req/s | 0.05 ms | 0.33 ms |
GET /hello/:n, 64 at once | 13,500 req/s | 3.1 ms | 17 ms |
POST /agents/Support (mock model), 64 at once | 12,800 req/s | 3.3 ms | 17 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
| Limit | Default | Over it |
|---|---|---|
| request body | 1 MB | 413 |
| time per request (or per WebSocket message) | 120 s | 504 |
| requests in flight | 64 | 503 with Retry-After |
| audio on one voice socket | 64 MB | error, 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 /mcpanswers 405). - A voice WebSocket has no live
heard/saidevents and no textsayorinterruptmessages 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).
intis 32-bit, so a JSON number over 2,147,483,647 in a request needsfloat.