---
title: "Go SDK"
url: "https://docs.caracal.run/sdks/go/"
markdown_url: "https://docs.caracal.run/markdown/sdks/go.md"
description: "Public API reference for the Go Caracal SDK."
page_type: "page"
concepts: []
requires: []
---

# Go SDK

Canonical URL: https://docs.caracal.run/sdks/go/
Markdown URL: https://docs.caracal.run/markdown/sdks/go.md
Description: Public API reference for the Go Caracal SDK.
Page type: page
Concepts: none
Requires: none

---

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

## Install

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

## Connect and Configure

```go
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

```go
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](/sdks/verification-layer/) 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.

## Related pages

- [Integrate the Go SDK](/guides/sdk-go/)
- [Verification Layer Overview](/sdks/verification-layer/)
- [Enforce, propagate, or attribute](/concepts/authority-model/#enforce-propagate-or-attribute)
- [Protect a Go net/http Service](/guides/protect-nethttp/)
- [Agent Delegation](/concepts/delegation/)