Reference · The tin command
- 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
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.
$ 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.
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)
} $ 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:
fn main() {
let total = 0
for n in [1, 2, 3] {
total = total + n
}
sleep(100)
print(total)
} $ 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.
$ 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.
$ 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.
fn area(w:int,h:int):int{w*h}
fn main(){print(area(3,4))} $ 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
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 fixapplies). - 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+):
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 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 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.
$ 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.
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.
$ 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.
tin mcp
tin mcp file.tin serves the file's tool fns as an MCP
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"] }.
// 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):
→ {"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.
tin build --target wasi
Builds a WASI 0.2 component: 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 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).
$ 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:
$ 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.
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/).
$ tin build hello.tin --native
hello native executable, 110656 bytes
$ ./hello
Hello from Tin! It needs wasm2c from 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.
$ 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).
$ 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.
$ 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 |
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 is this API in a Web Worker.
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.