Skip to content

Go SDK

The Go SDK provides agent lifecycle, delegation, Gateway routing, and context propagation for Go services.

Install

go get github.com/garudex-labs/caracal/packages/sdk/go

Connect and Configure

import caracal "github.com/garudex-labs/caracal/packages/sdk/go"

client, err := caracal.New()
if err != nil {
  return err
}

New() loads CARACAL_CONFIG, a caracal.toml in the default config path, or environment variables. FromEnv(), FromConfig(), and FromClientSecret() are available when you need explicit control.

Core methods

API	Purpose
`New()`	Auto-detect profile or environment configuration.
`FromEnv()`	Load from environment variables.
`FromConfig(path)`	Load a runtime profile.
`FromClientSecret(options)`	Use STS client-secret exchange for root SDK operations.
`client.Spawn(ctx, fn, opts...)`	Create an agent session and run `fn` with a bound `context.Context`; set `SpawnOptions.Grant` to bound the child’s authority.
`client.Delegate(ctx, opts, fn)`	Create a delegation edge from the current agent session.
`client.Headers(ctx, opts...)`	Project the bound context to `http.Header`.
`client.BindFromRequest(ctx, req, opts...)`	Bind inbound Caracal envelope headers.
`client.Transport(base, opts...)`	Return an `*http.Client` that injects Caracal headers.
`client.GatewayRequest(resourceID, path)`	Build explicit Gateway routing metadata.
`client.Current(ctx)`	Inspect the current Caracal context.

Context Propagation

constraints := &caracal.DelegationConstraints{
  MaxHops:        1,
  Budget:         5,
  PolicyApproved: true,
}

Available fields are Resources, MaxDepth, MaxHops, TTLSeconds, Budget, PolicyApproved, ExpiresAt, and BroadReason.

Protect Inbound Requests

Use BindFromRequest() to propagate a Caracal context after an upstream Gateway, connector, or transport verifier has accepted the inbound mandate. Use Verification Layer Overview when the Go service must enforce mandate signatures, scopes, targets, agent identity, delegation, or revocation at its own boundary.

Headers and Transport require a bound Caracal context by default. Pass caracal.RootOptions{AllowRoot: true} only when the call should intentionally use the application subject token.