Typed, repeatable operations for Linux hosts.
osapi lets an AI agent manage Linux hosts through typed operations, not through a login. Each operation is a behavior: one thing on a host, defined one time, with a fixed input and output. osapi checks each request before it queues it. A second run changes nothing. Each change is recorded.
The agent does not guess commands. It asks osapi what exists, and osapi answers with the behaviors that this binary has. No model runs at run time. The same input always does the same thing.
- 🤖 The agent asks the binary.
osapi behavior get,osapi help --jsonandosapi skill getgive each input, output, permission and skill. The agent reads them before it acts. - 🛠️ The agent can build a behavior. A behavior is one directory. osapi generates its API, CLI command, permission, docs and tests.
- 🔁 A second run is safe. A write reports
changed: trueone time. After that, it reportschanged: false. - 🌐 One host or the fleet. Target a hostname, any host, each host, or a label
such as
group:web. Each host answers for itself. - 📬 A slow host does not stop you. A request becomes a job, and the agent on each host runs it. There is no SSH.
- 🔍 You can see what occurred. osapi keeps each job, an audit log and OpenTelemetry traces. A secret input never goes to a log or a trace.
- 🔐 Root is a decision, not a default. Command exec is off until you turn it on. Work is under way so that the agent does not run as root.
- 🖥️ A dashboard, an API, a CLI and a Go SDK, from one binary.
osapi manages the hostname, DNS, network interfaces and routes, NTP, the timezone, packages, services, users, files, kernel parameters, cron, certificates, containers, processes, logs and power. Core concepts tells how the parts fit together.
Install the skills with osapi init, then ask your agent:
- "Set vm.swappiness to 10 on each host in group:web, and tell me which hosts changed."
- "Which hosts have package updates?"
- "Find each host with disk or memory pressure."
- "Add a behavior that manages the message of the day."
The agent finds the behavior, runs it with --json, and reads the result of
each host. You can run the same commands from the CLI.
osapi starts with behaviors on hosts. The next steps make it a platform for automation:
- Workflows: a file with named, ordered behavior calls. osapi checks the file before it runs. A step can run only where an earlier step changed something.
- Behaviors on one system: a behavior that runs on the controller, not on a fleet host. For example, it gets data from AWS, and a workflow then uses that data to configure the hosts.
- Scheduled workflows: a workflow declares a schedule, and osapi runs it.
- More behaviors: each hand-written domain moves to a behavior, one at a time.
The design pages in osapi-io/specs have the plans.
Cockpit and webmin give a person a web console for one server. [Ansible] pushes configuration over SSH. osapi is built for an agent:
- The agent asks osapi what exists, and gets typed answers for each host.
- The agent can build a new behavior, and each osapi user then gets it.
- There is no SSH. A request is a job, and a slow host does not block the others.
- Workflows of behaviors are next.
Why osapi has the full comparison, and when to use the others.
The docs give these steps:
- Start osapi.
- Give your agent its skills with
osapi init. - Ask for what you want.
- Run the same operations from the CLI.
The docs also tell how to build a behavior, by hand or with an agent.
| Project | Description |
|---|---|
| gohai | A Go-based system fact collector inspired by Chef Ohai |
| nats-client | A Go package for connecting to and interacting with a NATS server |
| nats-server | A Go package for running an embedded NATS server |
| osapi-justfiles | Shared justfiles this repository fetches its recipes from |
| osapi-lab | A fleet of real machines that runs a checkout of osapi |
| osapi-orchestrator | A Go package for orchestrating operations across OSAPI-managed hosts |
| specs | The design record for this repository, under components/osapi/ |
Refer to the Contributing guide for the prerequisites, the setup, the conventions and the PR workflow.
The MIT License.