# Tomte

> Small agents that do one job, in Go.

Web page: https://tomte.run/

A tomte is the farm spirit that quietly does the chores at night. A Tomte agent is a Go program that does one task, on a schedule or when asked, and compiles to one small binary: about 6 MB, and about 11 MB of memory while it waits.

```sh
go get github.com/berkaycubuk/tomte
```

Early: its author runs agents with it, but the API may change before v1.0.

## An agent

```go
package main

import (
	"context"
	"os"

	"github.com/berkaycubuk/tomte"
	"github.com/berkaycubuk/tomte/channels/telegram"
)

type args struct {
	Days int `json:"days" jsonschema:"minimum age in days"`
}

func findOverdue(ctx context.Context, in args) ([]Invoice, error) { … }

func main() {
	tomte.New("invoice-chaser",
		tomte.Instructions("You chase unpaid invoices. …"),
		tomte.Model("https://openrouter.ai/api/v1", "z-ai/glm-4.6", os.Getenv("MODEL_KEY")),
		tomte.Tool("find_overdue", "List unpaid invoices older than N days", findOverdue),
		tomte.Cron("0 9 * * 1-5", "Chase invoices overdue by 14 days or more."),
		tomte.SendTo(telegram.New(os.Getenv("TELEGRAM_TOKEN"), os.Getenv("TELEGRAM_CHAT"))),
		tomte.Price(0.60, 2.20),
		tomte.MaxCost(0.50, 5.00),
	).Run()
}
```

```
./invoice-chaser run "chase the invoices from March"   # one task, now
./invoice-chaser                                       # serve: run on the schedules
./invoice-chaser info                                  # what it is, as JSON
```

## Safe to leave alone

Every run has a step, time and dollar limit, and a run that fails or stops says so through the agent’s channel.

## Just Go

Tools, jobs and commands are Go functions, and the configuration is Go code: no YAML, no plugins, no dependencies.

## One command to deploy

tomte deploy builds the agent, uploads it over ssh and runs it as a sandboxed systemd service. Nothing else runs on the machine.

## One binary, one command

An agent is one binary and an env file, run by systemd. Each runs as its own throwaway user, can write only its state directory, and is capped at 128 MB of memory and half a CPU.

```sh
go install github.com/berkaycubuk/tomte/cmd/tomte@latest

tomte setup box                                   # once per machine
tomte deploy -env hn-digest.env box ./examples/hn-digest
tomte ls box
```

```
AGENT       STATE        MEMORY   NEXT RUN    LAST RUN               TODAY
hn-digest   active 3h    9.8M     Mon 08:00   2h ago, sent           1 run, $0.004 of $0.25
```

## What it isn't

Tomte isn’t a personal assistant: it’s for many small agents, each doing one job. So it has no browser, no long-term memory, no user accounts and no code written by the model. It uses only Go’s standard library and is MIT licensed.

## Links

- Source and docs: https://github.com/berkaycubuk/tomte#readme
- Examples: https://github.com/berkaycubuk/tomte/tree/main/examples
- Repository: https://github.com/berkaycubuk/tomte