Skip to main content

Home

A CRUD API for managing Linux systems.

This project provides basic management capabilities to Linux systems, enabling them to be used as appliances. You install a single binary, point it at a config file, and get a REST API and CLI for querying and changing system configuration — hostname, DNS, disk usage, memory, load averages, and more.


Install​

go install github.com/retr0h/osapi@latest

Or download a prebuilt binary from the releases page.

Docker​

A multi-arch distroless image is published to GitHub Container Registry on every commit to main. Images are signed with cosign (keyless, via GitHub OIDC) and include an SBOM attestation.

docker pull ghcr.io/osapi-io/osapi:latest
docker run ghcr.io/osapi-io/osapi:latest --help

Verify the image signature:

cosign verify ghcr.io/osapi-io/osapi:latest \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp github.com/osapi-io/osapi

Verify build provenance and SBOM attestations via the GitHub CLI:

gh attestation verify oci://ghcr.io/osapi-io/osapi:latest \
  --owner osapi-io

Attestations are also visible on the package page.

Quickstart​

Install OSAPI and start all three components in a single process:

osapi start

Or start each component separately:

osapi nats server start &
osapi api server start &
osapi agent start &

Generate a token and configure the CLI:

# Generate a signing key
export OSAPI_API_SERVER_SECURITY_SIGNING_KEY=$(openssl rand -hex 32)

# Generate a bearer token
osapi token generate -r admin -u [email protected]

# Set the token for CLI use
export OSAPI_API_CLIENT_SECURITY_BEARER_TOKEN=<token from above>

Query the system:

# Get the hostname
osapi client node hostname

# Check node status
osapi client node status

# View health
osapi client health

Explore the Docs​

  • Features — what OSAPI can manage and how each feature works
  • Architecture — how the three processes (NATS, API server, agent) fit together
  • Configuration — full osapi.yaml reference
  • API — OpenAPI documentation for all endpoints
  • CLI Usage — command reference with examples
  • Roadmap — current capabilities and what's next

Alternatives​