OSAPI SDK

Go SDK for OSAPI — client library and orchestration primitives.

📦 Install

go get github.com/osapi-io/osapi-sdk

🔌 SDK Client

Typed Go client for every OSAPI endpoint. See the client docs for targeting, options, and quick start.

Service	Operations	Docs	Source
Node	Hostname, disk, memory, load, uptime, OS info, status	docs	node.go
Network	DNS get/update, ping	docs	node.go
Command	exec, shell	docs	node.go
Job	Create, get, list, delete, retry, stats	docs	job.go
Agent	List, get (discovery + heartbeat data)	docs	agent.go
Health	Liveness, readiness, status	docs	health.go
Audit	List, get, export	docs	audit.go
Metrics	Prometheus text	docs	metrics.go

Targeting

Most operations accept a target parameter to control which agents receive the request:

Target	Behavior
_any	Send to any available agent (load balanced)
_all	Broadcast to every agent
hostname	Send to a specific host
key:value	Send to agents matching a label

Agents expose labels (used for targeting) and structured system details (OS, CPU, memory, network interfaces) via client.Agent.Get(). An additional Facts map carries open-ended data from agent-side providers.

🔀 Orchestration

DAG-based task execution on top of the client. See the orchestration docs for hooks, error strategies, and adding new operations.

Feature	Description	Source
DAG execution	Dependency-based ordering with automatic parallelism	plan.go
Op tasks	Declarative OSAPI operations with target routing and params	task.go
TaskFunc	Custom Go functions with SDK client access	task.go
TaskFuncWithResults	Custom functions that receive completed results from prior tasks	task.go
Hooks	8 lifecycle callbacks — consumer-controlled logging	options.go
Error strategies	StopAll, Continue (skip dependents), Retry(n)	options.go
Guards	When predicates, OnlyIfChanged conditional execution	task.go
Changed detection	Read-only ops return false, mutators reflect actual state	runner.go
Result access	Results.Get() for cross-task data flow, Status for outcome inspection	result.go
Broadcast results	Per-host HostResult data for multi-target operations	result.go

Operations

Operation	Description	Idempotent	Docs
node.hostname.get	Get system hostname	Read-only	docs
node.status.get	Get node status	Read-only	docs
node.disk.get	Get disk usage	Read-only	docs
node.memory.get	Get memory stats	Read-only	docs
node.uptime.get	Get system uptime	Read-only	docs
node.load.get	Get load averages	Read-only	docs
network.dns.get	Get DNS configuration	Read-only	docs
network.dns.update	Update DNS servers	Yes	docs
network.ping.do	Ping a host	Read-only	docs
command.exec.execute	Execute a command	No	docs
command.shell.execute	Execute a shell string	No	docs

📋 Examples

Each example is a standalone Go program you can read and run.

SDK Client

Example	What it shows
agent	Agent discovery, details, and facts
audit	Audit log listing, get, and export
command	Command exec and shell execution
health	Liveness, readiness, and status checks
job	Job create, get, list, delete, and retry
metrics	Prometheus metrics retrieval
network	DNS get/update and ping
node	Hostname, disk, memory, load, uptime

Orchestration

Example	What it shows
basic	Simple DAG with dependencies
broadcast	Multi-target operations with per-host results
error-strategy	StopAll vs Continue error handling
guards	When predicates for conditional execution
hooks	Lifecycle callbacks for logging and progress
only-if-changed	Skip tasks when dependencies report no changes
only-if-failed	Run tasks only when a dependency fails
parallel	Automatic parallelism for independent tasks
result-decode	Decode result data into typed structs
retry	Retry error strategy with configurable attempts
task-func	Custom Go functions with SDK client access
task-func-results	Cross-task data flow via Results.Get()

cd examples/osapi/node
OSAPI_TOKEN="<jwt>" go run main.go

📖 Documentation

See the generated documentation for package-level API details.

🤝 Contributing

See the Development guide for prerequisites, setup, and conventions. See the Contributing guide before submitting a PR.

📄 License

The MIT License.