Baton Chapter 1
About Baton
Baton is an API client whose collections, environments and schedules are plain YAML files in a git repository you own. There is no cloud account holding your work and no proprietary sync protocol: the repository is the product’s backbone, so anything git can do — branches, review, history, blame — applies to your requests as well.
It runs from one codebase on macOS, Windows, Linux, iOS, Android and in a browser. The screenshots in this manual are of the browser build at baton.dudko.dev/app, version 0.2.10; the desktop and mobile builds show the same screens, and Section 16 says what a desktop adds.
1.1The pieces
The app is what you are looking at. The worker is an optional server you run yourself — it executes scheduled runs and relays requests for the browser build. The MCP server lets an AI agent — Claude Code, Cursor, VS Code, Codex — read, edit and run requests, through the open app when there is one (Section 14). None of them is a service of ours; the worker and the MCP server are programs you start.
1.2What is in a workspace
A workspace is a directory, and everything in it is readable without Baton.
| Path | What it holds |
|---|---|
collections/ | One YAML file per request, in folders that mirror the tree |
environments/ | One file per environment: variable values, and the names of secrets |
schedules/ | What the worker should run, and when |
.baton/ | Run history and local state — not something you edit |
baton.yaml | Workspace settings: timeouts, redirects, TLS, proxy |
1.3What this manual covers
The chapters follow the order you meet things in: the window, then a workspace and the requests in it, then sending one and reading what came back, then the parts that make a request reusable — variables, secrets, auth, bodies, scripts — and finally collection runs, git sync, the worker, AI agents and settings.