dome

README

Dome Go SDK

Go client SDK for the Dome Platform — agent registration, authentication, and governance.

Install

go get github.com/Dome-Systems/sdk-dome-go

Quick Start

package main

import (
    "context"
    "log"
    "os"

    dome "github.com/Dome-Systems/sdk-dome-go"
)

func main() {
    // Initialize with credentials from `dome agents register`.
    if err := dome.Init(dome.WithCredentials(os.Getenv("DOME_AGENT_TOKEN"))); err != nil {
        log.Fatal(err)
    }
    defer dome.Shutdown(context.Background())

    // Register your agent.
    agent, err := dome.Register(context.Background(), dome.RegisterOptions{
        Name: "my-agent",
    })
    if err != nil {
        log.Fatal(err)
    }

    log.Printf("Registered agent %s (ID: %s)", agent.Name, agent.ID)
    // Your agent runs here. Heartbeat is automatic.
}

Authentication

The SDK accepts credentials in several ways (checked in order):

1. dome.WithCredentials(token) — opaque credential blob from dome agents register
2. dome.WithAPIKey(key) — static API key
3. DOME_AGENT_TOKEN environment variable
4. DOME_API_KEY environment variable
5. DOME_TOKEN environment variable

The recommended approach is WithCredentials with the token from dome agents register, which includes Vault OIDC authentication automatically.

Documentation

Full documentation is available at docs.domesystems.ai.

License

MIT License. See LICENSE for details.

Documentation

Overview

Package dome provides a Go client SDK for the Dome Platform.

The SDK handles agent registration, heartbeat, policy checks, and lifecycle management. Agents integrate with a few lines of code and heartbeat automatically.

Quick start using the global client:

dome.Init(dome.WithCredentials(os.Getenv("DOME_AGENT_TOKEN")))
defer dome.Shutdown(context.Background())

agent, err := dome.Start(ctx, dome.StartOptions{
    Name: "my-agent",
})

For explicit client management:

client, err := dome.NewClient(
    dome.WithCredentials(os.Getenv("DOME_AGENT_TOKEN")),
    dome.WithAPIURL("https://api.dome.example.com"),
)
defer client.Close()

agent, err := client.Start(ctx, dome.StartOptions{
    Name: "my-agent",
})

Index

• Constants
• func Init(opts ...Option) error
• func Middleware(next http.Handler) http.Handler
• func Shutdown(_ context.Context) error
• type AgentInfo
  • func Register(ctx context.Context, opts RegisterOptions) (*AgentInfo, error)
  • func Start(ctx context.Context, opts StartOptions) (*AgentInfo, error)
• type CheckRequest
• type Client
  • func NewClient(opts ...Option) (*Client, error)
  • func (c *Client) AgentID() string
  • func (c *Client) Check(_ context.Context, req CheckRequest) (*Decision, error)
  • func (c *Client) Close() error
  • func (c *Client) Middleware(next http.Handler) http.Handler
  • func (c *Client) Register(ctx context.Context, opts StartOptions) (*AgentInfo, error)
  • func (c *Client) Start(ctx context.Context, opts StartOptions) (*AgentInfo, error)
• type Decision
  • func Check(ctx context.Context, req CheckRequest) (*Decision, error)
• type Option
  • func WithAPIKey(key string) Option
  • func WithAPIURL(url string) Option
  • func WithCredentials(token string) Option
  • func WithCredentialsFile(path string) Option
  • func WithGracefulDegradation() Option
  • func WithHeartbeatInterval(d time.Duration) Option
  • func WithLogger(l *slog.Logger) Option
  • func WithPolicyRefresh(d time.Duration) Option
  • func WithoutHeartbeat() Option
  • func WithoutPolicy() Option
• type RegisterOptions
• type StartOptions

Constants

const (
	// DefaultAPIURL is the default Dome API server address for local development.
	DefaultAPIURL = "http://localhost:8080"

	// DefaultHeartbeatInterval is the SDK-side heartbeat interval.
	// This is half the server deadline (60s) to give one retry before
	// the agent appears stale.
	DefaultHeartbeatInterval = 30 * time.Second

	// DefaultPolicyRefreshInterval is how often the SDK fetches the policy
	// bundle from the control plane.
	DefaultPolicyRefreshInterval = 5 * time.Minute
)

Functions

func Init

func Init(opts ...Option) error

Init initializes the global Dome client. Call this once at startup. Options configure authentication, API URL, and logging.

If no credentials are provided, Init attempts to read from DOME_AGENT_TOKEN, DOME_API_KEY, or DOME_TOKEN environment variables (in that order).

func Middleware

func Middleware(next http.Handler) http.Handler

Middleware wraps an http.Handler with Dome governance using the global client. Currently logs requests. Policy enforcement will be added in a future version.

func Shutdown

func Shutdown(_ context.Context) error

Shutdown gracefully stops the global client, stopping the heartbeat goroutine and releasing resources. It is safe to call Shutdown multiple times.

Types

type AgentInfo

type AgentInfo struct {
	ID           string
	Name         string
	Status       string
	Capabilities []string
	Metadata     map[string]string
	Token        string
}

AgentInfo holds the result of a successful registration.

func Register

func Register(ctx context.Context, opts RegisterOptions) (*AgentInfo, error)

Register is a deprecated alias for Start.

Deprecated: renamed to Start in v0.3.0.

func Start

func Start(ctx context.Context, opts StartOptions) (*AgentInfo, error)

Start announces the agent to the Dome control plane using the global client. Init must be called before Start.

type CheckRequest

type CheckRequest struct {
	// Action is the operation being performed (e.g., "mcp:call", "llm:chat").
	Action string
	// Resource is the target of the action (e.g., "hr-mcp/get_salary", "openai/gpt-4").
	Resource string
	// ResourceType optionally specifies the resource category: "mcp", "llm",
	// "credential". If empty, it is inferred from Action.
	ResourceType string
	// Context provides additional key-value pairs for policy evaluation.
	Context map[string]string
}

CheckRequest describes a policy evaluation request.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the Dome SDK client. It handles agent registration, heartbeat, and Cedar policy evaluation. Use NewClient to create one, or use the global Init/Start/Shutdown functions.

func NewClient

func NewClient(opts ...Option) (*Client, error)

NewClient creates a new Dome SDK client.

Authentication is resolved in priority order:

1. Explicit WithCredentials option (base64 credential blob)
2. Explicit WithAPIKey option
3. DOME_AGENT_TOKEN environment variable (credential blob)
4. DOME_API_KEY environment variable
5. DOME_TOKEN environment variable (backwards compatibility)

func (*Client) AgentID

func (c *Client) AgentID() string

AgentID returns the registered agent's ID, or empty if not yet registered.

func (*Client) Check

func (c *Client) Check(_ context.Context, req CheckRequest) (*Decision, error)

Check evaluates a policy decision against the locally cached Cedar policy bundle. If no policies are loaded (bundle not yet fetched, or policy disabled), Check returns allowed (fail-open for v0.4.0; fail-closed in v1.0).

func (*Client) Close

func (c *Client) Close() error

Close stops the background heartbeat goroutine, policy syncer, and releases resources. It is safe to call Close multiple times.

func (*Client) Middleware

func (c *Client) Middleware(next http.Handler) http.Handler

Middleware wraps an http.Handler with Dome governance. Each incoming request is evaluated against the Cedar policy bundle. If denied, the request receives a 403 Forbidden response with the denial reason.

If no policies are loaded, all requests are allowed (fail-open for v0.4.0).

func (*Client) Register

func (c *Client) Register(ctx context.Context, opts StartOptions) (*AgentInfo, error)

Register is a deprecated alias for Start. Use Start instead.

Deprecated: renamed to Start in v0.3.0.

func (*Client) Start

func (c *Client) Start(ctx context.Context, opts StartOptions) (*AgentInfo, error)

Start announces the agent to the Dome control plane and begins background heartbeat. The agent must already be registered via `dome agents register` (CLI) — Start announces it as online, not creates the identity.

If an agent with the same name already exists (CodeAlreadyExists), Start finds the existing agent and returns its info. This makes Start idempotent and safe to call on every startup.

On success, Start begins a background heartbeat goroutine (unless WithoutHeartbeat was used).

If WithGracefulDegradation was set and the call fails (e.g. API unreachable), Start logs a warning and retries in the background instead of returning an error. AgentID returns empty until background registration succeeds.

type Decision

type Decision struct {
	// Allowed indicates whether the action is permitted.
	Allowed bool
	// Reason provides a human-readable explanation of the decision.
	Reason string
	// PolicyVersion is the version of the policy bundle used for evaluation,
	// or empty if no policies are loaded.
	PolicyVersion string
}

Decision is the result of a policy evaluation.

func Check

func Check(ctx context.Context, req CheckRequest) (*Decision, error)

Check evaluates a policy decision using the global client. Currently always returns allowed. Policy enforcement will be added in a future version.

type Option

type Option func(*clientConfig)

Option configures the SDK client.

func WithAPIKey

func WithAPIKey(key string) Option

WithAPIKey sets a static API key for authentication. This is a simpler alternative to WithCredentials for development or testing.

func WithAPIURL

func WithAPIURL(url string) Option

WithAPIURL sets the Dome API server URL.

func WithCredentials

func WithCredentials(token string) Option

WithCredentials sets the opaque credential token (base64-encoded blob from `dome agents register`). The SDK decodes this to extract Vault auth config automatically.

func WithCredentialsFile

func WithCredentialsFile(path string) Option

WithCredentialsFile reads the credential token from a file.

func WithGracefulDegradation

func WithGracefulDegradation() Option

WithGracefulDegradation enables background retry on registration failure. When set, Register returns nil error on failure and retries in the background. The agent starts immediately. AgentID returns empty until registration succeeds.

func WithHeartbeatInterval

func WithHeartbeatInterval(d time.Duration) Option

WithHeartbeatInterval sets the heartbeat interval. Must be positive.

func WithLogger

func WithLogger(l *slog.Logger) Option

WithLogger sets a custom slog logger. By default, the SDK uses slog.Default().

func WithPolicyRefresh

func WithPolicyRefresh(d time.Duration) Option

WithPolicyRefresh sets the policy bundle refresh interval. Default: 5 minutes. Set to 0 to disable periodic refresh (manual only).

func WithoutHeartbeat

func WithoutHeartbeat() Option

WithoutHeartbeat disables the background heartbeat goroutine.

func WithoutPolicy

func WithoutPolicy() Option

WithoutPolicy disables policy evaluation. Check() always returns allowed.

type RegisterOptions

type RegisterOptions = StartOptions

StartOptions configures the agent announcement to the control plane.

Deprecated: RegisterOptions was renamed to StartOptions in v0.3.0.

type StartOptions

type StartOptions struct {
	Name         string
	Description  string
	ParentID     string
	Capabilities []string
	Metadata     map[string]string
}

StartOptions configures the agent announcement to the control plane.