client

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 15, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package client is the public Go SDK for the Wardyn control plane.

It mirrors the REST API surface of wardynd exactly — same paths, same status codes, same JSON vocabulary (internal/types is the shared source of truth). The SDK adds zero non-stdlib dependencies so it can be embedded in external tooling without dependency friction. (The in-repo `wardyn` CLI keeps its own minimal client in cmd/wardyn/client.go.)

Usage: 

c := client.New("https://wardyn.example.com", "admin-token")
run, err := c.CreateRun(ctx, client.CreateRunRequest{
    Agent: "claude-code",
    Repo:  "org/repo",
    Task:  "fix issue #42",
})

Index

Constants

View Source 
const (
	ApprovalPending  = types.ApprovalPending
	ApprovalApproved = types.ApprovalApproved
	ApprovalDenied   = types.ApprovalDenied
	ApprovalExpired  = types.ApprovalExpired
)

ApprovalState values. ListApprovals accepts one of these (or "" for all states).

View Source 
const (
	RunPending   = types.RunPending
	RunStarting  = types.RunStarting
	RunRunning   = types.RunRunning
	RunWaiting   = types.RunWaiting
	RunStopped   = types.RunStopped
	RunArchived  = types.RunArchived
	RunFailed    = types.RunFailed
	RunKilled    = types.RunKilled
	RunCompleted = types.RunCompleted
)

RunState values.

View Source 
const (
	CC1 = types.CC1
	CC2 = types.CC2
	CC3 = types.CC3
)

ConfinementClass values.

View Source 
const (
	GrantGitHubToken = types.GrantGitHubToken
	GrantCloudSTS    = types.GrantCloudSTS
	GrantAPIKey      = types.GrantAPIKey
)

GrantKind values.

View Source 
const (
	ApprovalCredential   = types.ApprovalCredential
	ApprovalEgressDomain = types.ApprovalEgressDomain
	ApprovalToolCall     = types.ApprovalToolCall
)

ApprovalKind values.

View Source 
const (
	ActorHuman  = types.ActorHuman
	ActorAgent  = types.ActorAgent
	ActorSystem = types.ActorSystem
)

ActorType values.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	// Status is the HTTP status code, e.g. 404.
	Status int
	// Body is the raw server response body (capped at 2048 bytes).
	Body string
}

APIError is returned when the server responds with a non-2xx status code. Status is the HTTP status code; Body is the raw response body (trimmed to 2 KiB) for diagnostic display. Callers may use errors.As to extract it.

func (*APIError) Error 

func (e *APIError) Error() string

type ActorType 

type ActorType = types.ActorType

ActorType distinguishes who performed an audited action (AuditEvent.ActorType).

type AgentRun 

type AgentRun = types.AgentRun

AgentRun is one governed execution of a coding agent. Returned by CreateRun, GetRun, and ListRuns.

type ApprovalKind 

type ApprovalKind = types.ApprovalKind

ApprovalKind enumerates what a human is being asked to approve (ApprovalRequest.Kind).

type ApprovalRequest 

type ApprovalRequest = types.ApprovalRequest

ApprovalRequest is a human-in-the-loop approval gate. Returned by ListApprovals, Approve, and Deny.

type ApprovalState 

type ApprovalState = types.ApprovalState

ApprovalState is the approval lifecycle state; ListApprovals filters on it (ApprovalRequest.State).

type AuditEvent 

type AuditEvent = types.AuditEvent

AuditEvent is one append-only audit record. Returned by AuditEvents.

type Client 

type Client struct {
	// BaseURL is the wardynd root, e.g. "https://wardyn.example.com".
	// A trailing slash is stripped automatically.
	BaseURL string

	// Token is the admin bearer token configured in wardynd (AdminToken).
	Token string

	// HTTPClient, when non-nil, is used instead of http.DefaultClient.
	HTTPClient *http.Client

	// Principal, when non-empty, is sent as the X-Wardyn-Principal header.
	// This overrides the server-side principal attribution for multi-user dev;
	// in production the token's subject is used instead.
	Principal string
}

Client is the Wardyn SDK client. Construct it with New or by filling the fields directly. BaseURL and Token are required; HTTPClient defaults to http.DefaultClient when nil.

All methods accept a context; the context controls cancellation and deadline for the underlying HTTP call.

func New 

func New(baseURL, token string) *Client

New returns a Client configured with baseURL and token.

func (*Client) Approve 

func (c *Client) Approve(ctx context.Context, id uuid.UUID, reason string) (types.ApprovalRequest, error)

Approve transitions an approval request to APPROVED. reason is optional; pass an empty string to omit it. Returns 409/APIError when the approval has already been decided. Returns 404/APIError when the approval does not exist.

func (*Client) AuditEvents 

func (c *Client) AuditEvents(ctx context.Context, runID uuid.UUID) ([]types.AuditEvent, error)

AuditEvents returns the append-only audit trail for the specified run. run_id is required by the server; a zero UUID will be rejected with 400.

func (*Client) CreatePolicy 

func (c *Client) CreatePolicy(ctx context.Context, req PolicyRequest) (types.RunPolicy, error)

CreatePolicy validates and persists a new policy. Returns the created RunPolicy (status 201) on success; 400 on an invalid name or spec.

func (*Client) CreateRun 

func (c *Client) CreateRun(ctx context.Context, req CreateRunRequest) (types.AgentRun, error)

CreateRun submits a new agent run to the control plane. Returns the created AgentRun (state PENDING or RUNNING) on success. Status 201 on success; 400 on validation failure; 422 on policy/confinement mismatch; 503 when the runner is unavailable.

func (*Client) DeletePolicy 

func (c *Client) DeletePolicy(ctx context.Context, id uuid.UUID) error

DeletePolicy removes a policy by id. Returns nil on success (204); 404/APIError when the policy does not exist.

func (*Client) DeleteSecret 

func (c *Client) DeleteSecret(ctx context.Context, name string) error

DeleteSecret removes a named secret. DELETE /api/v1/secrets/{name}. Returns 403 for a reserved platform-internal name.

func (*Client) Deny 

func (c *Client) Deny(ctx context.Context, id uuid.UUID, reason string) (types.ApprovalRequest, error)

Deny transitions an approval request to DENIED (fail closed). reason is optional; pass an empty string to omit it. Returns 409/APIError when the approval has already been decided. Returns 404/APIError when the approval does not exist.

func (*Client) GetPolicy 

func (c *Client) GetPolicy(ctx context.Context, id uuid.UUID) (types.RunPolicy, error)

GetPolicy fetches a single RunPolicy by its UUID. Returns 404/APIError when the policy does not exist.

func (*Client) GetRun 

func (c *Client) GetRun(ctx context.Context, id uuid.UUID) (types.AgentRun, error)

GetRun fetches a single AgentRun by its UUID. Returns 404/APIError when the run does not exist.

func (*Client) KillRun 

func (c *Client) KillRun(ctx context.Context, id uuid.UUID) (KillRunResponse, error)

KillRun initiates the kill sequence for a run: sandbox teardown, identity revocation, credential revocation, then state transition to KILLED. Returns 202/Accepted with the final state on success. Returns 404/APIError when the run does not exist.

func (*Client) ListApprovals 

func (c *Client) ListApprovals(ctx context.Context, state types.ApprovalState) ([]types.ApprovalRequest, error)

ListApprovals returns approval requests filtered by state. Pass an empty string to return all states. Valid states: "PENDING", "APPROVED", "DENIED", "EXPIRED" (types.ApprovalState).

func (*Client) ListGrants 

func (c *Client) ListGrants(ctx context.Context, runID uuid.UUID) ([]types.CredentialGrant, error)

ListGrants returns the credential-grant eligibility records for a run. These are eligibility records (what the run MAY request), not issued credentials — some may never be minted. Returns 404/APIError when the run does not exist.

func (*Client) ListPolicies 

func (c *Client) ListPolicies(ctx context.Context) ([]types.RunPolicy, error)

ListPolicies returns all run policies in reverse creation order.

func (*Client) ListRuns 

func (c *Client) ListRuns(ctx context.Context) ([]types.AgentRun, error)

ListRuns returns all runs in reverse creation order.

func (*Client) ListSecrets 

func (c *Client) ListSecrets(ctx context.Context) ([]string, error)

ListSecrets returns the managed secret NAMES (never values). Reserved platform-internal keys are excluded server-side. GET /api/v1/secrets, which responds {"names":[...]}.

func (*Client) SetSecret 

func (c *Client) SetSecret(ctx context.Context, name, value string) error

SetSecret stores (or overwrites) a named secret. The value is write-only — no API path ever returns it. PUT /api/v1/secrets/{name} with body {"value":...}. Returns 400 on an invalid name, 403 for a reserved platform-internal name.

func (*Client) UpdatePolicy 

func (c *Client) UpdatePolicy(ctx context.Context, id uuid.UUID, req PolicyRequest) (types.RunPolicy, error)

UpdatePolicy validates and replaces an existing policy's name and spec. Returns the updated RunPolicy on success; 404 when unknown; 400 when invalid.

type ConfinementClass 

type ConfinementClass = types.ConfinementClass

ConfinementClass declares how strongly a sandbox confines an agent (AgentRun.ConfinementClass, RunPolicySpec.MinConfinementClass).

type CreateRunRequest 

type CreateRunRequest struct {
	Agent    string     `json:"agent"`
	Repo     string     `json:"repo"`
	Task     string     `json:"task,omitempty"`
	PolicyID *uuid.UUID `json:"policy_id,omitempty"`
	// ConfinementClass, when set, requests a specific confinement class
	// ("CC1"/"CC2"/"CC3"). Empty inherits the policy minimum; an unknown
	// non-empty value is rejected by the server with 400.
	ConfinementClass string `json:"confinement_class,omitempty"`
	// Interactive requests an interactive run: the sandbox comes up idle (no
	// agent task is exec'd) so a human can attach to it (wardyn attach <id>).
	// Pair with a never-reap policy (AutoStopAfterSec < 0) or the idle reaper
	// will stop the idle sandbox. Task is ignored for an interactive run.
	Interactive bool `json:"interactive,omitempty"`
	// InlinePolicy, when set, supplies the run's full RunPolicySpec INLINE
	// instead of referencing a stored PolicyID. It is MUTUALLY EXCLUSIVE with
	// PolicyID (the server rejects both with 400); neither set falls back to the
	// configured default. The server validates it exactly like a stored policy
	// (mounts pass the same deny-list; api_key grants must reference an existing
	// secret) and attaches it with no stored policy id.
	InlinePolicy *RunPolicySpec `json:"inline_policy,omitempty"`
}

CreateRunRequest is the body for POST /api/v1/runs.

type CredentialGrant 

type CredentialGrant = types.CredentialGrant

CredentialGrant is a credential-grant eligibility record. Returned by ListGrants.

type GrantKind 

type GrantKind = types.GrantKind

GrantKind enumerates broker-mintable credential kinds (GrantSpec.Kind).

type GrantSpec 

type GrantSpec = types.GrantSpec

GrantSpec is a credential scope description carried in RunPolicySpec.EligibleGrants.

type KillRunResponse 

type KillRunResponse struct {
	ID    uuid.UUID      `json:"id"`
	State types.RunState `json:"state"`
}

KillRunResponse is the body returned by POST /api/v1/runs/{id}/kill.

type PolicyRequest 

type PolicyRequest struct {
	Name string              `json:"name"`
	Spec types.RunPolicySpec `json:"spec"`
}

PolicyRequest is the body for POST/PUT /api/v1/policies. Name is required; Spec is validated server-side before persistence (a bad spec is rejected with 400, fail closed).

type RunPolicy 

type RunPolicy = types.RunPolicy

RunPolicy is a declarative policy attached to runs. Returned by the policy methods (ListPolicies, GetPolicy, CreatePolicy, UpdatePolicy).

type RunPolicySpec 

type RunPolicySpec = types.RunPolicySpec

RunPolicySpec is the policy body carried in PolicyRequest.Spec. As a true `=` alias it carries the full wire surface, including AllowAllEgress (json:"allow_all_egress,omitempty") for the "allow all (deny-list only)" egress mode — no separate SDK struct to keep in sync.

type RunState 

type RunState = types.RunState

RunState is the AgentRun lifecycle state (AgentRun.State, KillRunResponse.State).

type WorkspaceMount 

type WorkspaceMount = types.WorkspaceMount

WorkspaceMount is an operator/policy-controlled host bind mount carried in RunPolicySpec.WorkspaceMounts.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.