Skip to content
osapi-ioPublic

About

Typed, repeatable operations for Linux hosts. Give your agent a fleet, not a shell.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

1 watching

Forks

Latest commit

 

History

947 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

osapi

Typed, repeatable operations for Linux hosts.

release codecov license build docker cosign sbom powered by conventional commits openapi initiative Linux gitHub commit activity go reference

Give your agent a fleet, not a shell

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.

✨ Features

  • 🤖 The agent asks the binary. osapi behavior get, osapi help --json and osapi skill get give 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: true one time. After that, it reports changed: 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.

💬 What you can ask

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.

🧭 Where osapi goes next

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.

⚖️ Alternatives

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.

🚀 Getting started

The docs give these steps:

  1. Start osapi.
  2. Give your agent its skills with osapi init.
  3. Ask for what you want.
  4. Run the same operations from the CLI.

The docs also tell how to build a behavior, by hand or with an agent.

📚 Documentation

🧩 Sister projects

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/

🤝 Contributing

Refer to the Contributing guide for the prerequisites, the setup, the conventions and the PR workflow.

📄 License

The MIT License.

About

Typed, repeatable operations for Linux hosts. Give your agent a fleet, not a shell.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages