<!-- The tin command · Tin · https://tin.ad/docs/ref/cli/ · 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/)
-  [Deploying](https://tin.ad/docs/ref/deploy/)
-  [tin.ad](https://tin.ad/docs/ref/cloud/)
-  [The tin command](https://tin.ad/docs/ref/cli/)
- [Usage](#usage)
- [tin run](#run)
- [tin test](#test)
- [tin check and tin fix](#check)
- [tin fmt](#fmt)
- [tin lsp and editors](#lsp)
- [tin add and tin install](#add)
- [tin repl](#repl)
- [tin tools and tin caps](#tools)
- [tin build](#build)
- [tin mcp](#mcp)
- [tin build --target wasi](#wasi)
- [tin build --native](#native)
- [tinc](#tinc)
- [tin deploy](#deploy)
- [Environment variables](#env)
- [Exit codes](#exit)
- [Using the compiler from JavaScript](#embed)
-  [How it works](https://tin.ad/docs/ref/internals/)

**Reference · The tin command

- [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

- [Usage](#usage)
- [tin run](#run)
- [tin test](#test)
- [tin check and tin fix](#check)
- [tin fmt](#fmt)
- [tin lsp and editors](#lsp)
- [tin add and tin install](#add)
- [tin repl](#repl)
- [tin tools and tin caps](#tools)
- [tin build](#build)
- [tin mcp](#mcp)
- [tin build --target wasi](#wasi)
- [tin build --native](#native)
- [tinc](#tinc)
- [tin deploy](#deploy)
- [Environment variables](#env)
- [Exit codes](#exit)
- [Using the compiler from JavaScript](#embed)

# The tin command

Running, checking, fixing and inspecting programs from the terminal.

## Usage

From a checkout, the command is `./bin/tin`. It needs Node 24 or newer and nothing
else for programs that do not call a real model.

<!-- output -->
```text
$ tin help
tin 0.1.0 — a small typed language with agents built in, compiled to WebAssembly

start:
  tin new <name> [--plain]                create a project (an agent example; --plain for hello world)
  tin new <name> --template hello-agent   an agent ready to deploy: tin deploy main.tin --target cloudflare
  tin run <file.tin> [args] [flags]       compile and run; args (and all after --) go to args()
  tin repl [--yes]                        type Tin and see the result (every entry is compiled to wasm)
  tin test <file.tin> [--replay <tape>]   run the test "name" { ... } blocks in a file

packages:
  tin add <git url|path> [--name n] [--rev r]   add a dependency to tin.toml, fetch it, pin it in tin.lock
  tin install [--frozen]                  fetch everything in tin.toml at the commits in tin.lock

inspect:
  tin check <file.tin> [--json]           type-check only; --json prints diagnostics with fixes
  tin fix <file.tin>                      apply the compiler's suggested fixes until the file compiles
  tin fmt <file.tin>... [--check]         format in place (one style, no options); --check only lists files that need it
  tin tools <file.tin>                    print the JSON schemas generated for tool fns
  tin caps <file.tin> [--reach <name>]    what each agent and tool can reach, and what needs approval
  tin mcp <file.tin> [--yes]              serve the file's tool fns as an MCP server on stdin/stdout
  tin serve <file.tin> [--port n]         run the file's server (or its agents as endpoints) on localhost; reloads on save
  tin lsp                                 a language server on stdin/stdout, for any editor
  tin doc [file.tin...] [-o dir] [--json] API docs from /// comments (default: the project's files, into doc/)

ship:
  tin build <file.tin> [-o out.wasm]      compile to a .wasm file (for the JS host: tin run, the browser, Node)
  tin build <file.tin> --target wasi      a .wasm for any WASI runtime, no JS:  wasmtime run hello.wasm
  tin build <file.tin> --native           a native executable (via wasm2c and your C compiler):  ./hello
  tin build <file.tin> --native --cross linux-arm64|linux-x64   a static Linux executable (zig cc)
  tin build <file.tin> --target <platform> [-o dir] [--repo <github url>]   a deployable server: cloudflare, vercel,
                                          cloudrun, azure, lambda; --repo puts a one-click Deploy button in dir/DEPLOY.md
  tin deploy <file.tin> [--name n]                   to https://<name>.tin.ad (anonymous: 24 h; --yes sends env secrets)
  tin deploy <file.tin> --target <platform> [--yes]   build, set its secrets in the platform's store (asks first), upload
  tin ls | tin logs [name] | tin rm <name>           your tin.ad deployments (keys in ~/.tin/cloud.json)
  tin logs -f [--level error] [--grep text]          follow the logs live
  tin requests [name] [-f] [--status 5xx]            recent requests: status, duration, tokens, model, trace id
  tin traces [name] [--errors] | tin traces <name> <id>  traces, or one trace as a tree
  tin metrics [name] [--range 1h|24h|7d]             requests, errors, latency, tokens, est. cost
  tin login | tin logout | tin whoami                GitHub sign-in for tin.ad: deploys are kept and owned, --name works
  tin secrets [ls|set NAME|unset NAME] [--app name]   a tin.ad deployment's secrets (value asked, never argv)
  tin register [name] [--agent A] [--chain base-sepolia] [--agent-id N]   EIP-8004 on a testnet (opt-in; your wallet)
  tin version

run flags:
  --trace           print each agent-loop step (model calls, tool calls, results) to stderr
  --yes             approve every guarded tool call without asking
  --record <tape>   save every model response, fetch, input and random number to a tape
  --replay <tape>   run from a tape: no network, no model, the same answers
  --mic <file.wav|->      what mic() hears: a WAV file, or raw 24 kHz PCM16 on stdin (default: sox if installed)
  --speaker <file.wav>    where speaker() plays: written as WAV at exit (default: sox, or afplay on macOS)

examples:
  tin new hello && tin run hello/main.tin
  tin run examples/agents/08-fleet.tin --replay tests/tapes/agents-08-fleet.json --yes
  tin caps examples/agents/07-capabilities.tin --reach wireMoney
```

## tin run

Compiles the file in memory and runs it. Nothing is written to disk. Output goes to standard
output; compile errors, panics and the agent trace go to standard error.

| Flag | Effect |
| --- | --- |
| `--trace` | prints every step of every agent loop: model calls, tool calls and their results |
| `--yes` | approves every `guarded` tool call. Without it, a terminal is asked `y/N`, and a run with no terminal denies. |
| `--record <tape>` | saves model responses, `fetch` results, `input` lines and random numbers to a JSON file |
| `--replay <tape>` | runs from such a file, with no model and no network |

 Input can be piped: `echo "hello" | tin run chat.tin` gives each `input()`
call the next line.

The words after the file are the program's `args()`, and so is everything after
`--`, flags included: `tin run app.tin -- --yes` gives the program
`["--yes"]` and approves nothing. A flag before `--` that tin does not know is an
error (exit code 2) rather than being dropped.

## tin test

Runs every `test "name" { ... }` block in a file. Each test gets a fresh instance
of the program. A failing test shows why, and anything it printed.

```tin
fn half(n: int): int => n / 2

test "even numbers" {
  assertEq(half(10), 5)
}

test "odd numbers round down" {
  print("checking 9")
  assertEq(half(9), 5)
}
```

<!-- output -->
```text
$ tin test half.tin
✔ even numbers
✖ odd numbers round down
    assertEq(half(9), 5): expected 5, got 4
    | checking 9

1 passed, 1 failed
```

 The exit code is 1 if any test failed. `--replay tape.json` gives every test the
same recorded model responses; `--yes` approves guarded tools, which are otherwise denied.

## tin check and tin fix

`tin check` compiles without running. Take this file, `sum.tin`:

```tin
fn main() {
  let total = 0
  for n in [1, 2, 3] {
    total = total + n
  }
  sleep(100)
  print(total)
}
```

<!-- output -->
```text
$ tin check sum.tin
error: 'total' is immutable
 --> sum.tin:4:5
  |
4 |     total = total + n
  |     ^^^^^
  = note: declare it with `var total = ...` to allow reassignment
  = fix: declare total with var

error: expected Duration, found int
 --> sum.tin:6:9
  |
6 |   sleep(100)
  |         ^^^
  = note: a Duration needs a unit: write 100ms or 2s, or `n * 1ms` for a number in a variable
  = fix: add a unit: ms

2 errors
```

 The compiler reports every error it can find in one run, in source order: each function, test and
agent is checked on its own, and inside a block a failing statement is set aside so the rest is still
checked (a statement that uses a name the failing one should have declared is skipped, so one mistake is
reported once). A syntax error stops the run at that point. With `--json` the errors are
machine-readable, and its `fix` is an exact edit: replace the characters from
`start` to `end` with `text`.

<!-- output -->
```text
$ tin check sum.tin --json
{
  "ok": false,
  "diagnostics": [
    {
      "message": "'total' is immutable",
      "file": "sum.tin",
      "line": 4,
      "col": 5,
      "endLine": 4,
      "endCol": 10,
      "notes": [
        "declare it with `var total = ...` to allow reassignment"
      ],
      "fix": {
        "label": "declare total with var",
        "line": 2,
        "col": 3,
        "endLine": 2,
        "endCol": 6,
        "text": "var",
        "start": 14,
        "end": 17
      }
    },
    {
      "message": "expected Duration, found int",
      "file": "sum.tin",
      "line": 6,
      "col": 9,
      "endLine": 6,
      "endCol": 12,
      "notes": [
        "a Duration needs a unit: write 100ms or 2s, or `n * 1ms` for a number in a variable"
      ],
      "fix": {
        "label": "add a unit: ms",
        "line": 6,
        "col": 9,
        "endLine": 6,
        "endCol": 12,
        "text": "100ms",
        "start": 85,
        "end": 88
      }
    }
  ]
}
```

 `tin fix` applies the first fix the errors offer, checks again, and repeats until the file
compiles or no error left has an automatic fix (an error without one does not stop the fixes after it).
A `let` whose value is wrong but whose type is written keeps that type, so code using it is
still checked; a typo in a name, function or field gets "did you mean" and a fix. It rewrites the file in place. A fix that makes something up, such as a
missing field's starting value (`y: 0.0`) or a `match` arm that panics until you write it, is
listed at the end as a placeholder to check; in `--json` its `fix` has a `placeholder` field.

<!-- output -->
```text
$ tin fix sum.tin
sum.tin:4: 'total' is immutable
  fix: declare total with var
sum.tin:6: expected Duration, found int
  fix: add a unit: ms
sum.tin: compiles after 2 fix(es)
$ tin run sum.tin
6
```

 Not every error has a fix. Those that do include habits from other languages (`"total: " + n`,
`for (let i = 0; i < n; i++)`, `{"a": 1}`, `and`/`or`,
`s[0]`, `let mut`, `x++`, `===`, `elif`, `not x`, `f"..."`, `:=`, `xs.size()`, `Math.sqrt`, `x.toString()`, `->` return types), a missing struct
field (added with a starting value), a `match` on numbers or strings without `_`, a struct
literal in an `if`/`for` header, an unmet trait bound (a stub method), a missing
bound inside a bounded generic, `<` on a struct without `compare`,
`Map()`, assigning to a `let`, mixing
`int` and `float`, a value where a `string`, `Option` or
`Duration` is expected, a `match` with missing arms, `null`, a
mistyped built-in type name, a plain `fn` in an agent's tools, and an unguarded tool
that reaches guarded code.

## tin fmt

Rewrites a file in the one standard layout. There are no options to argue about.
`tin fmt --check` changes nothing and fails if the file is not already formatted.

```tin
fn   area(w:int,h:int):int{w*h}
fn main(){print(area(3,4))}
```

<!-- output -->
```text
$ tin fmt messy.tin && cat messy.tin
fn area(w: int, h: int): int { w * h }
fn main() { print(area(3, 4)) }
```

## tin lsp and editors

`tin lsp` is a [Language Server Protocol](https://microsoft.github.io/language-server-protocol/)
server on stdin and stdout, so any editor with an LSP client can use it (VS Code, Neovim, Helix, Zed,
Emacs). It runs the real parser and checker on the unsaved buffer and answers:

- **Problems as you type**, with the compiler's suggested fix as a quick fix (the same fix `tin fix` applies).
- **Hover**: the type the checker inferred (`let p: Point`), or a function's signature, with its `///` doc. Standard library functions show their one-line description.
- **Go to definition** and **find references** for locals, parameters, fields, methods, types, variants and agents, across files joined with `import "./x.tin"`.
- **Rename**, which refuses keywords and standard-library names.
- **Completion**: after `x.`, the fields and methods of x's type; elsewhere, the names in scope first.
- **Outline** (document symbols) and **Format Document** (`tin fmt`).

The checker stops at the first error, so the editor shows one problem at a time. Everything checked
before that error still has its types. In Neovim (0.11+):

```tin
vim.lsp.config('tin', { cmd = { 'tin', 'lsp' }, filetypes = { 'tin' }, root_markers = { '.git' } })
vim.lsp.enable('tin')
```

 The VS Code extension in `editors/vscode` starts `tin lsp` for you; see its README to install it.

The [playground](https://tin.ad/docs/play/) runs the same editor core in a Web Worker: every error is underlined (hover one for its
message), hovering a name shows its type and doc, and typing `.` or Ctrl+Space opens completion.

## tin add and tin install

`tin add <git url|path> [--name n] [--rev r]` adds a dependency to `tin.toml` (creating
it if there is none above the current folder), fetches it into `.tin/pkgs/`, and writes
`tin.lock`. Without `--name`, the name comes from the package's own `tin.toml`, else
the repository or folder name. Adding a name again moves it to the newest commit (or to `--rev`).
If anything fails, `tin.toml` is left as it was.

`tin install [--frozen]` fetches every dependency at its locked commit and checks its checksum.
See [Packages](https://tin.ad/docs/ref/language/#packages) for how imports find a package.

## tin repl

Type Tin and see the result. Every entry is compiled to WebAssembly like a file is, so the REPL
follows the same rules as a program. An expression prints its value; `let`, `var`
and loops run as statements; `fn`, `type`, `agent` and `tool fn`
are kept and can be redefined; `import "./x.tin"` (with or without `as`) brings in a
file. `:list` shows the session as one program, `:reset` forgets it.

Bindings survive because each entry runs the session again with earlier output hidden. What earlier
entries took from outside is replayed, not asked for again: a model reply, a `fetch`, a line of
`input`, a random number, an approval. Only the new entry reaches the model or the person.
The clock is not replayed, and anything an entry does through JavaScript (`import js`) happens
again.

<!-- output -->
```text
$ tin repl
tin> let name = input("name? ")
name? Ada
tin> "hi " + name               // input is not asked for again
hi Ada
tin> name.len
3
```

## tin tools and tin caps

`tin tools file.tin` prints the JSON Schemas the compiler generated for every
`tool fn`: exactly what a model is shown. `tin caps file.tin` reports what
each agent can reach and what needs approval; `--reach name` lists the agents and
functions that can reach one function, and `--json` prints the report as JSON.
Both are described, with their output, under [Agents and tools](https://tin.ad/docs/ref/agents/#capabilities).

## tin build

Writes the WebAssembly module to a file. The module is self-describing: it carries the tool
schemas and type layouts in a custom section, so the runtime needs nothing but the
`.wasm`.

<!-- output -->
```text
$ tin build hello.tin
hello.wasm  1037 bytes
```

 **Not yet:** there is no `tin run hello.wasm`; a built module is
run through the [JavaScript API](#embed).

## tin mcp

`tin mcp file.tin` serves the file's `tool fn`s as an [MCP](https://modelcontextprotocol.io/)
server over standard input and output, so any MCP client (Claude Desktop, Claude Code, Cursor, another Tin
program) can call them. The tool list carries the same JSON Schemas a Tin agent sends its model: from the
parameter types and `///` docs. A tool that returns a struct also gets an `outputSchema`
and answers with structured content; `Result` errors come back as `isError` results.
An argument the schema does not list is refused (the schema says `additionalProperties: false`), and
an `int` parameter carries its 32-bit `minimum` and `maximum`. The file
needs no `main`. What the program prints goes to standard error, never into the protocol.

A `guarded tool fn` is refused (the call is denied, as for an agent without approval) unless the
server was started with `--yes`: the protocol has no person to ask. For a client config:
`{ "command": "tin", "args": ["mcp", "/path/to/units.tin"] }`.

```tin
// A Tin program as an MCP server: its tool fns become MCP tools, with schemas from the types.
//
//   tin mcp examples/mcp/units.tin
//
// Add it to any MCP client (Claude Desktop, Claude Code, Cursor, ...) as a stdio server:
//   { "command": "tin", "args": ["mcp", "/path/to/units.tin"] }

/// A temperature in one unit, converted to the others.
type Temperatures = {
  celsius: float,
  fahrenheit: float,
  kelvin: float,
}

/// Convert a temperature. `unit` is "C", "F" or "K".
tool fn convert(
  /// the temperature to convert
  value: float,
  /// its unit: "C", "F" or "K"
  unit: string,
): Result<Temperatures, string> {
  let c = match unit {
    "C" => value,
    "F" => (value - 32.0) * 5.0 / 9.0,
    "K" => value - 273.15,
    _ => return Err("unknown unit '{unit}': use C, F or K"),
  }
  if c < -273.15 {
    return Err("{value}{unit} is below absolute zero")
  }
  Ok(Temperatures { celsius: c, fahrenheit: c * 9.0 / 5.0 + 32.0, kelvin: c + 273.15 })
}

/// How many seconds are in a number of minutes, hours or days.
tool fn seconds(amount: int, unit: string): int {
  match unit {
    "min" => amount * 60,
    "h" => amount * 3600,
    "d" => amount * 86400,
    _ => amount,
  }
}
```

A session, two messages each way (from this build of the docs):

<!-- output -->
```text
→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"docs","version":"1"}}}
← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{"listChanged":false}},"serverInfo":{"name":"units","version":"0.1.0"}}}
→ {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"convert","arguments":{"value":212,"unit":"F"}}}
← {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"{\"celsius\":100,\"fahrenheit\":212,\"kelvin\":373.15}"}],"isError":false,"structuredContent":{"celsius":100,"fahrenheit":212,"kelvin":373.15}}}
```

 The other direction, a Tin program calling an MCP server, is [import mcp](https://tin.ad/docs/ref/language/#mcp).

## tin build --target wasi

Builds a [WASI 0.2 component](https://component-model.bytecodealliance.org/): it imports only
`wasi:cli`, `wasi:io`, `wasi:clocks`, `wasi:random` and `wasi:filesystem` (version 0.2.6) and
exports `wasi:cli/run`, so [wasmtime](https://wasmtime.dev/) runs it with no JavaScript host and
no Tin installed. Output is the same, byte for byte, as `tin run`: numbers are formatted by the same
rules, and a panic prints the same message and exits with 1. Add `--preview1` for a WASI preview-1 core
module with a `_start` instead, for runtimes without components (wasmer, Node's `node:wasi`).

<!-- output -->
```text
$ tin build hello.tin --target wasi
hello.wasm  95658 bytes
$ wasmtime run hello.wasm
Hello from Tin!
```

 `input()` reads standard input, `env()` reads the environment the runtime passes in
(`wasmtime run --env NAME=value`), `args()` the words after the module
(`wasmtime run hello.wasm a b`), and `exit(code)` sets the exit status;
`now()` and `sleep()` use the WASI clocks. A native executable reads its own
command line and environment the same way. Exit codes other than 0 and 1 use
`wasi:cli/exit.exit-with-code`, which WASI 0.2.6 still marks unstable; wasmtime answers it without a flag.
`examples/wasi/stats.tin` is a small command-line tool built this way.

Files (`readFile`, `writeFile`, `readBytes`, `writeBytes`, `exists`,
`isDir`, `listDir`) reach only the directories the runtime gives the module:
`wasmtime run --dir . app.wasm` for the working directory, `--dir /data` for another. A path under
none of them is an `Err` that says so (`permission denied (not under a directory given with --dir)`);
every other result and error text is the same as under `tin run`. A native executable reads and writes files
like any other program on the machine, with the same texts.

`fetch` and std `http()` (streamed bodies too) go through `wasi:http`: only a program
that uses them imports `wasi:http/outgoing-handler@0.2.6`, so run it with `wasmtime run -S http app.wasm`
(a pure program needs no flag). A failed request gives the same `Err` text as under `tin run`.
Headers the runtime owns (`host`, `connection`, `transfer-encoding`, …) are not sent, as in a browser.
A program with a `server` (and no `main`) becomes a `wasi:http/incoming-handler` component:
`wasmtime serve -S cli app.wasm` answers its routes like `tin serve` (same statuses, JSON, 404/405, `/healthz`),
one fresh instance per request. Its agent endpoints answer too: `GET /`, `GET` and `POST /agents/<Name>` and
`POST /mcp`, with the same JSON as `tin serve`, and a file with agents and neither `main` nor `server` becomes a server
of their endpoints, as with `tin serve`. Two differences: there are no WebSocket endpoints (`wasi:http` 0.2 has no
connection upgrade, so `ws` routes are refused at build time and the index lists none), and an event stream arrives whole
(the reply as one `text` event, then `done`, when the agent has finished).
Tasks work too: `spawn`, `await`, `within`, `stop` and `sleep` are scheduled inside the module
(a waiting task's stack is saved to memory and resumed later; no threads, no JavaScript), with the same output as `tin run`.
`approve` asks the question `tin run` asks, on stderr, when stdin is a terminal; with a pipe or a file on stdin the answer is no, as in `tin run`;
set `TIN_APPROVE=all`, `none` or a comma-separated list of tool names to decide without asking.
Agents work: their loop, tools and `on` handlers are compiled into the module (with the `mock` model, the same
output and token counts as `tin run`), and so are the model providers, which are written in Tin: `bedrock:…`
(`AWS_BEARER_TOKEN_BEDROCK`), `anthropic:…`/`claude-…` (`ANTHROPIC_API_KEY`) and `openai:…`
(`OPENAI_API_KEY`, `OPENAI_BASE_URL`). Keys come from the environment: `wasmtime run -S http --env AWS_BEARER_TOKEN_BEDROCK=… app.wasm`.
Typed replies, `A.try`, agents as tools and guarded tools (asked as under `approve`) work too.
Not on WASI yet, and refused at build time with the reason: `code: true`, i64 tool parameters, enums with data in tool parameters, voice agents, and `import js`:

<!-- output -->
```text
$ tin build ask.tin --target wasi
ask.wasm  381708 bytes
```

 **Differences from `tin run`:** `sin`, `cos`, `tan`,
`ln` and `pow` use fdlibm and can differ from Node in the last bit (about 1 input in 100;
the result is the same on every machine). A trap that is not a Tin panic, such as division by zero or a stack
overflow, is reported by the runtime in its own words (wasmtime exits with 134). A panic prints the same message,
backtrace (`in …` lines) and exit code as `tin run`. The component is about 70 KB
bigger than the JS-host build: the host functions are compiled in.

## tin deploy

`tin build app.tin --target cloudflare|vercel|cloudrun|azure|lambda` writes a deployable folder;
`tin deploy app.tin --target cloudflare|vercel` also stores the program's keys in the platform's secret store
(after asking) and uploads it. `tin new hello --template hello-agent` is a project ready for it. The whole
story, the target table and the checks are on [Deploying](https://tin.ad/docs/ref/deploy/).

## tin build --native

Builds a native executable: one file, no Node, no wasm runtime. It links the program with Tin's runtime
for the Tin Host ABI, turns that into C with `wasm2c` and compiles the C with your C
compiler (`cc`, or `$CC`), together with a small host in C (`src/native/`).

<!-- output -->
```text
$ tin build hello.tin --native
hello  native executable, 110656 bytes
$ ./hello
Hello from Tin!
```

 It needs `wasm2c` from [wabt](https://github.com/WebAssembly/wabt) 1.0.34 or newer
and a C compiler. `sh scripts/install-native.sh` (in a Tin checkout) puts wabt 1.0.42 and
Mbed TLS 3.6.7 in `~/.tin`, pinned by checksum; `brew install wabt` works too, and
`TIN_WASM2C` points at a specific binary. Output, panics, traps and exit codes are the same as
`tin run`.

`fetch` and `http()` work natively: `http://` and `https://` over HTTP/1.1, with TLS
from Mbed TLS linked into the executable, so it still depends only on the C library. Certificates are checked
against the system's roots (`/etc/ssl/cert.pem` on macOS; `SSL_CERT_FILE` overrides).
A program that fetches is about 660 KB instead of 90 KB. A failed fetch gives the same `Err` text as under `tin run` (connection refused, cannot resolve host, certificate not trusted, blocked port).
Tasks and `approve` work as under WASI. Without a JavaScript host (WASI and native) Tin runs agents with tools, memory, typed replies, A.try, A.save / restore, guarded tools and agents as tools (the mock model and real ones), spawn and tasks, approve, files (with the directories the runner gives: wasmtime --dir), panics with their backtrace, fetch() and http(), telemetry spans (console, or OTLP/HTTP JSON when the program uses the network), and servers with their agent endpoints (POST /agents/<Name>, /mcp; an event stream arrives whole). Not yet: WebSocket routes (native), spawn inside a server, tool parameters of type i64 or an enum with data, robot worlds other than the built-in kinematic one (MuJoCo) (WASI) and learned robot policies (onnx, hub, remote). Not without JavaScript, by design: WebSocket routes (WASI), because wasi:http 0.2 has no connection upgrade; code: true agents (agent-written code), because running code the model wrote needs the Tin compiler and a wasm engine inside the program; voice agents and audio, because they need audio devices and a realtime model session over a WebSocket, which the JavaScript host provides; import js / mcp / py and extern fn, because they call into a JavaScript or Python host.

Agents work natively as under WASI (above), real models included: the agent loop and the providers written in Tin
are compiled into the executable, so a hello agent on Bedrock is one file of about 950 KB that needs nothing but its key.
Against the same OpenAI-compatible server, a native agent sends the same requests and prints the same output as
`tin run`; `npm run smoke:native` checks it live on Bedrock.

<!-- output -->
```text
$ tin build examples/agents/hello-native.tin --native -o hello
hello  native executable, 947576 bytes
$ AWS_BEARER_TOKEN_BEDROCK=… ./hello
Hello! 3 times 4 equals 12.
```

 A file with a `server` and no `main` builds a server: the executable listens on
`$PORT`, else the port in `grants [net.listen(8080)]`, else 8080, and answers each
connection in a fresh process with a fresh instance, so one request can never see another's memory. Its
routes answer exactly as under `tin serve` (status, headers, JSON bodies, 404/405/413), and so do its agent
endpoints, as under WASI (no WebSocket endpoints, an event stream arrives whole). Not natively yet: `ws` routes
(use `tin serve` or `tin deploy`).

<!-- output -->
```text
$ tin build api.tin --native
api  native executable, 162384 bytes
$ PORT=3000 ./api
listening on http://localhost:3000
```

 `--cross linux-arm64` or `--cross linux-x64` builds a Linux executable from macOS or any other
machine: one static file (musl, no shared libraries, no loader), compiled with `zig cc` (`zig` on the PATH,
`TIN_ZIG`, or `pip install ziglang`). Programs that fetch need Mbed TLS built for the target once:
`CC="zig cc -target aarch64-linux-musl" AR="zig ar" TIN_TLS_TARGET=linux-arm64 sh scripts/install-native.sh tls`.
The hello agent is 1.2 MB for linux-arm64. `npm run parity:linux` builds every example for both targets and runs them on
Linux (directly on a Linux machine, or in a Lima VM from a Mac), compared with `tin run`: 430 of 430 identical on Ubuntu 26.10
(linux-arm64 on the arm64 kernel, linux-x64 under `qemu-x86_64`), and the hello agent answers live on Bedrock from both.

Recursion gets a 512 MiB stack, so it goes much deeper than under Node.

## tinc

`tinc` is the Tin compiler written in Tin (`compiler/*.tin`), as a command. It reads a program and the files it
imports (`import "./x.tin"`, `import "./x.tin" as name`, and packages from `tin.toml` with a
`path`), and writes the same `.wasm`, byte for byte, as `tin build`; its errors are the same text,
files, lines and columns as `tin check`. Built with `--native` it is one executable with no Node and no
wasm runtime, and it compiles its own source to the same bytes as `tin build` does.

<!-- output -->
```text
$ tin build compiler/tinc.tin --native -o tinc
tinc  native executable, 1456968 bytes
$ ./tinc build app.tin -o app.wasm
app.wasm  9784 bytes
$ ./tinc check app.tin
app.tin: ok
```

 The install script puts it in `~/.tin/bin/tinc` when a build for your machine is published (`TIN_TINC=0` skips it).
`tinc build` writes modules for the JavaScript host (`tin run`, the browser, Node); for
`--target wasi`, `--native` and the cloud targets use `tin build`. Packages from git are not
read by tinc yet (it says so, with exit status 3). Exit status: 0 ok, 1 the program has errors, 2 usage or a file it
cannot read, 3 something tinc does not do yet. `npm run parity:tinc` compares the native tinc with `tin`
on every file in `examples/`, building and checking.

## Environment variables

| Variable | Used for |
| --- | --- |
| `TIN_MODEL` | the model for agents that do not name one |
| `TIN_PROVIDER` | `fetch`: call the API without the SDK, with the provider a browser uses |
| `ANTHROPIC_API_KEY` | the Anthropic API |
| `TIN_THINKING` | Claude's extended thinking: `adaptive`, or a token budget such as `8000`; off by default |
| `TIN_PROMPT_CACHE` | `off`: no prompt caching for Claude (on by default) |
| `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `GEMINI_API_KEY`, `OLLAMA_HOST`, … | the other model providers: see [Model providers](https://tin.ad/docs/ref/providers/#table) |

 A program reads any variable with `env("NAME")`.

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | success |
| `1` | the program did not compile, panicked, or hit a runtime error; or `tin fmt --check` found unformatted code |
| `2` | the command line was wrong, or a file could not be read |
| `70` | a bug in Tin itself |

## Using the compiler from JavaScript

The compiler and the runtime are plain TypeScript modules with no dependencies. They run in Node
and in the browser; the [playground](https://tin.ad/docs/play/) is this API in a Web Worker.

```tin
import { compile, CompileError } from './src/compiler.ts'
import { instantiate } from './src/runtime.ts'

const { wasm, capabilities } = compile(source, 'main.tin')   // throws CompileError

const program = await instantiate(wasm, {
  write: (text) => process.stdout.write(text),               // print and write
  input: async (prompt) => readLine(prompt),                 // input()
  approve: async (tool, args) => askSomeone(tool, args),     // guarded tools
  models: (name) => ({ model: name, chat: myModel }),        // any model: one async function
  trace: (line) => console.error(line),
})

console.log(program.toolSpecs())                             // the generated schemas
await program.run()                                          // resolves when main and all tasks finish
```

 A model provider is one function, `chat(request)`, that takes the system prompt, the
messages and the tool schemas and returns the reply. Pass `record` or
`replay` with a tape to capture or reproduce a run. A `CompileError` carries
`diagnostic`, the same object `tin check --json` prints.
