Building a behavior with an agent
A behavior is one directory, and an agent can write all of it. The osapi binary
has a skill, build-a-behavior, with the procedure and the decisions: what to
ask before you write, which behavior to build on, and which checks prove that it
works. Use this to build most behaviors.
Your first behavior builds one by hand.
Behaviors is the reference for each part.
A behavior is work on a host. An operation of the controller itself, such as the
agents, the jobs or the audit log, is an endpoint. A second skill,
build-an-endpoint, covers it in the same way. The endpoint DSL makes the spec
of a group today, and the skill says to stop at the parts that are not built
yet. A command that runs in the CLI and calls no API, such as
osapi token generate, is a local command. A third skill, build-a-command,
covers it.
Set it up
Open a checkout of osapi with a coding agent. .claude/skills/build-a-behavior/
is a short pointer to the skill, and .agents/skills links to it. When the
request is about a behavior, the agent loads the pointer. The pointer tells it
to run go run . skill get --name build-a-behavior, and the binary prints the
skill. Thus the binary is the only source of the skill. osapi init does not
install it, because it is to change osapi, not to use it. Refer to
osapi skill. Build the binary one time, because
the binary embeds the UI:
mise exec -- just build
What to ask
Say what osapi must manage, not how:
- "Add a behavior that manages the message of the day in /etc/motd."
- "Add a behavior that lists the host's ARP and NDP neighbors, under network."
- "Add an internal behavior that installs and removes Debian packages, for other behaviors to require."
- "Let sysctl's list filter by whether osapi manages a parameter."
- "Give the sysctl behavior a provider for Fedora."
- "Migrate the timezone domain to a behavior."
What it will ask you
A wrong guess becomes an API someone depends on, so the agent settles these before it writes code, with a recommendation for each:
- whether a similar behavior exists, to extend it instead
- whether operators call it, or only other behaviors (an internal behavior)
- which platforms it runs on. All other platforms report
skipped - whether part of the work already exists as an internal behavior to require
- whether a value changes with each call (an input) or with each host (a setting)
- which programs it runs, which with sudo, and whether an input is a secret
- where the real state is: a file that osapi writes, a file that something else
owns, the output of a program, or
/proc - how "already done" looks, so that a second run changes nothing
What it writes, and how it proves it
It runs osapi behavior create. Then it writes the settings, the types, the
provider, the methods and the definition, with examples that are also the tests.
Then it runs the same checks as a person:
go generate ./internal/behaviors/all
mise exec -- just generate # the spec, SDK and UI clients, API docs
go run . behavior validate
mise exec -- just test # every check, 100% coverage per behavior
CI then runs the write examples against a real agent, as root, on its Linux runner.
Each failure names what to fix: an example with a wrong output, a write that changes the host on its second run, a field that lets a path or an option through, or a program that runs without a declaration. The table of the skill gives the fix for each one.
To review the result, read the definition in internal/behaviors/<name>/. Then
read osapi behavior get --name <name> and the generated page under
Behaviors. osapi generates all of the
rest of the change from those.
What it will refuse
The platform cannot do some things yet. Examples are a method that is an action, for example a restart, and not a create, update or delete; a command that the caller gives; and a resource under another resource. For those, the agent stops and says what is missing. It does not build around the gap. Each one is a change to the platform, and a person decides it.
Moving a hand-written domain
A hand-written domain moves in one change: you build its behavior and delete the
domain together. The two never run side by side. The checks name the code that
is left to delete: the route check names the directory of the hand-written
domain, and a test names each hand-written command that has the name of a
behavior command. references/migrating.md of the skill gives the procedure.