Build Go applications around the Obey daemon.
Installation · Quick start · Examples · API reference
Submit prompts, stream activity, and manage durable sessions from your Go application. The SDK uses the installed Obey CLI as its transport and has standard-library-only runtime dependencies.
The SDK is open source under Apache-2.0. The Obey daemon is proprietary and runs separately. See platform support for the verified runtime scope.
Requires Go 1.24+, a compatible Obey CLI on PATH, and a running Obey daemon
with your camp, provider, and model configured.
go get github.com/Obedience-Corp/obey-go-sdk@v0.2.0Import the public package:
import "github.com/Obedience-Corp/obey-go-sdk/pkg/obey"The version is recorded in your application's go.mod. See
compatibility for capability discovery and supported
machine protocols.
Install Obey through the Festival installer. Stable Obey 0.5.0 supports one-shot prompts through protocol v1. Persistent SDK APIs require a daemon and CLI that advertise the corresponding machine protocols; unsupported operations return a typed error before creating a session.
Use Providers, Models, RefreshModels and Preflight with Obey 0.5.0+ to
populate route selectors and check the selected route. Catalogs retain freshness,
unknown capabilities and raw IDs. Older CLIs return a typed unsupported_protocol
error; preserve manual route entry. When offering Obey alongside other backends,
construct its client only after Obey is selected.
See optional provider integration for routing,
readiness, permissions and streaming limits.
Replace the camp, provider, and model below with values configured in your daemon.
package main
import (
"context"
"fmt"
"log"
"github.com/Obedience-Corp/obey-go-sdk/pkg/obey"
)
func main() {
if err := run(context.Background()); err != nil {
log.Fatal(err)
}
}
func run(ctx context.Context) error {
client, err := obey.NewClientFromPath(obey.WithCamp("my-camp"))
if err != nil {
return err
}
defer client.Close()
result, err := client.RunPrompt(ctx, "Summarize the current project", &obey.RunOptions{
SessionOptions: obey.SessionOptions{
Provider: "your-provider",
Model: "your-model",
},
})
if err != nil {
return err
}
fmt.Println(result.Text)
return nil
}Daemon requests accept a context.Context, so HTTP request contexts and application
cancellation can flow through to the CLI operation.
On stable Obey 0.5.0, use RunPrompt or StreamPrompt with final-result fidelity.
The persistent workflows below require additional advertised machine protocols;
current stable Obey returns a typed unsupported_protocol error before mutation.
| Workflow | API |
|---|---|
| Discover daemon routes | Client.Providers, Client.Models, Client.RefreshModels |
| Check selected route requirements | Client.Preflight |
| Run a prompt | Client.RunPrompt, Client.StreamPrompt |
| Create or reopen a session | Client.CreateSession, Client.OpenSession |
| Submit durable work | Session.Send |
| Inspect or recover a turn | Client.OpenTurn, Turn.State, Turn.Wait |
| Read history and activity | Session.Transcript, Session.Attach, Client.Observe |
| Handle approvals | Session.PendingApprovals, Session.RespondApproval |
| Control work explicitly | Turn.Cancel, Session.Stop |
One-shot runs own their new session and attempt cleanup when they finish. Persistent sessions have a different lifetime: closing the client detaches, and your application decides when to cancel a turn or stop a session.
For durable submissions, persist your application's idempotency key before calling
Session.Send. Retain returned references, including partial references on errors,
for recovery. Send acknowledges acceptance; Turn.Wait retrieves the original turn's
result. Applications control mutation retries and approval decisions explicitly.
See lifecycle and recovery for ownership, cancellation, acceptance uncertainty, observation cursors, and retained-result behavior.
| Example | Demonstrates |
|---|---|
| Basic prompt | A one-shot prompt with explicit provider and model |
| Streaming | Incremental events and final results |
| Observation | Scoped activity streams and caller-controlled reconnect |
| Approvals | Inspecting pending calls and submitting explicit decisions |
| HTTP service | Using request contexts in a Go HTTP handler |
The persistent HTTP integration fixture demonstrates application-owned key/ref journaling, process restart, and explicit session controls. Its integration evidence records the tested scenarios.
| Platform | Status |
|---|---|
| Linux amd64 and arm64 | Festival-installed CLI/daemon integration verified |
| macOS arm64 | Isolated native SDK process lifecycle verified; see evidence |
| Windows | Unsupported |
The operator manages daemon startup, authentication, and provider configuration. See release notes for the current verification limits.
just build
just lint
just test unitSubprocess tests run in disposable Docker containers:
just test processKeep filesystem, socket, database, and child-process fixtures in the isolated test lanes. See integration evidence for real-daemon consumer checks.
Run the public-release integration with Docker and network access:
just test installedThis installs Obey through released Festival, exercises the SDK against the actual
daemon with a deterministic loopback provider, and verifies persisted session state.
It needs no private Obey checkout or provider credentials. CI runs it on pull
requests, pushes to main, and nightly to catch release compatibility regressions.
For SDK maintainers, release instructions describe source checks, immutable tags, automated publication and clean external import verification.
Apache License 2.0. The license covers this SDK; the Obey daemon is distributed separately under its own terms.