Onset for agents

Onset is made for agents: short output that says what to do next, exit codes that never change meaning, and ways to land with no folder on disk.

Give an agent the guide

on guide >> AGENTS.md

on guide prints the instructions for coding agents. Load it as a skill or add it to AGENTS.md.

Tokens

Agents and CI sign in with a token, not a browser. Make one in Tokens settings and set it:

export ONSET_TOKEN=<token>

A token acts for the person who made it. It can be limited to some projects, or to reading, and the host enforces that. A land with a read-only token waits for someone who can land.

ONSET_NAME and ONSET_EMAIL set the author of lands made with on land.

One workspace each

Give every agent its own folder with on get or on workspaces add. See Workspaces.

Output

Every command ends with a next: line. --json prints one JSON object with the same facts, plus next:

{
  "ok": false,
  "error": { "code": "conflict", "message": "can't land rtnb: 2 files conflict with main 48213" },
  "main": 48213,
  "conflicts": [
    { "path": "src/auth/login.ts", "kind": "text" },
    { "path": "assets/logo.png", "kind": "binary" }
  ],
  "next": ["on sync, fix the conflicts in those files, then on land"]
}

Exit codes

Exit	error.code	Meaning
0		It worked.
1	failed, not_found, empty_change, nothing_to_undo	It didn't work. The message says why.
2	bad_usage, no_description	The command was wrong. next shows the right form.
3	conflict	Run on sync, fix the marked files and land again.
4	checks_failed	Fix what the project's checks found.
5	waiting	A person has to approve or land it. Don't retry in a loop.
6	offline	The host can't be reached. The work is saved.
7	not_allowed, not_logged_in	Permissions.
8	secret	Remove the secret from that line.

Land without a workspace

One HTTP call lands file edits. It becomes a change of the caller's and lands like any other: merged with what landed since base, held for approvals or landing rights, and refused for secrets.

curl -X POST https://onset.coline.dev/v1/projects/acme/shop/edits \
  -H "Authorization: Bearer $ONSET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Add a release note",
    "base": 48213,
    "files": { "notes/release.md": "Shipped the new login.\n" }
  }'

Field	Meaning
title	What changed, in one line. Required.
body	Why, and what you checked.
files	Paths and their new text. null deletes a file.
files_base64	Paths and base64 content, for binary files.
executable	The paths to mark executable.
base	The version the edits were made on. Needed when you edit or delete files that exist.
key	Your own key for these edits. Sending it again answers as the first time.
allow_secrets	Lands even if the secret check flags something.

A file is sent whole, so an edit to a file that's already on main needs base. Without it, the edit would drop what others landed to that file since. One call takes up to 10,000 files.

The answer says what happened:

{
  "outcome": "landed",
  "version": { "n": 48214, "title": "Add a release note", "author": "Sam Rivera <sam@example.com>" },
  "change": "mbggfhghkjyn"
}

MCP

Upstream's host speaks MCP, with the same tokens:

https://onset.coline.dev/mcp

Tool	Does
onset_read	Reads a file from a version of main.
onset_list	Lists a folder.
onset_log	Shows the latest versions of main.
onset_land	Lands file edits, like the HTTP call.

Lands through the HTTP API or MCP are authored by the token's account.

Sessions

When an agent lands with on land, Onset keeps what it was asked, said and ran since its last land with the change. Anything that looks like a secret is removed.

• Only you can read it, plus people you share the change with. Your machine encrypts it before upload, so the host and the project's owners can't.
• It never reaches Git.
• on sessions show <change> prints one.
• on sessions off stops keeping them on this machine, and ONSET_SESSIONS=0 does it for one command.
• on sessions delete <change> deletes one here and on the host. --all deletes all of yours in the project.