<!-- Servers · Tin · https://tin.ad/docs/ref/server/ · generated from the built page -->

[Reference](https://tin.ad/docs/ref/)

-  [The language](https://tin.ad/docs/ref/language/)
-  [Agents and tools](https://tin.ad/docs/ref/agents/)
-  [Model providers](https://tin.ad/docs/ref/providers/)
-  [The Anthropic API](https://tin.ad/docs/ref/anthropic/)
-  [Talking agents](https://tin.ad/docs/ref/bidi/)
-  [Standard library](https://tin.ad/docs/ref/stdlib/)
-  [Glossary](https://tin.ad/docs/ref/glossary/)
-  [Package docs](https://tin.ad/docs/ref/api/)
-  [Telemetry](https://tin.ad/docs/ref/telemetry/)
-  [Robots](https://tin.ad/docs/ref/robot/)
-  [Servers](https://tin.ad/docs/ref/server/)
- [The server declaration](#decl)
- [Request and Response](#request)
- [What a handler returns](#answers)
- [Request taint](#taint)
- [Grants](#grants)
- [Agent endpoints](#endpoints)
- [WebSocket protocol](#ws)
- [Isolation and concurrency](#model)
- [Limits](#limits)
- [The handler contract](#contract)
- [What does not work yet](#gaps)
-  [Deploying](https://tin.ad/docs/ref/deploy/)
-  [tin.ad](https://tin.ad/docs/ref/cloud/)
-  [The tin command](https://tin.ad/docs/ref/cli/)
-  [How it works](https://tin.ad/docs/ref/internals/)

**Reference · Servers

- [The language](https://tin.ad/docs/ref/language/)
- [Agents and tools](https://tin.ad/docs/ref/agents/)
- [Model providers](https://tin.ad/docs/ref/providers/)
- [The Anthropic API](https://tin.ad/docs/ref/anthropic/)
- [Talking agents](https://tin.ad/docs/ref/bidi/)
- [Standard library](https://tin.ad/docs/ref/stdlib/)
- [Glossary](https://tin.ad/docs/ref/glossary/)
- [Package docs](https://tin.ad/docs/ref/api/)
- [Telemetry](https://tin.ad/docs/ref/telemetry/)
- [Robots](https://tin.ad/docs/ref/robot/)
- [Servers](https://tin.ad/docs/ref/server/)
- [Deploying](https://tin.ad/docs/ref/deploy/)
- [tin.ad](https://tin.ad/docs/ref/cloud/)
- [The tin command](https://tin.ad/docs/ref/cli/)
- [How it works](https://tin.ad/docs/ref/internals/)

On this page

- [The server declaration](#decl)
- [Request and Response](#request)
- [What a handler returns](#answers)
- [Request taint](#taint)
- [Grants](#grants)
- [Agent endpoints](#endpoints)
- [WebSocket protocol](#ws)
- [Isolation and concurrency](#model)
- [Limits](#limits)
- [The handler contract](#contract)
- [What does not work yet](#gaps)

# 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

```tin
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`).

```tin
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`):

```tin
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`.
