Skip to main content

​
Overview

Agent types represent compute environments monitored by Garnet. Each agent has a kind (GitHub, Kubernetes, or Vanilla) and context-specific metadata.

​
Agent

Represents a stored agent model with full details. 
type Agent struct {
    ID                string                  `json:"id"`
    ProjectID         string                  `json:"project_id"`
    OS                string                  `json:"os"`
    Arch              string                  `json:"arch"`
    Hostname          string                  `json:"hostname"`
    Version           string                  `json:"version"`
    IP                string                  `json:"ip"`
    MachineID         string                  `json:"machine_id"`
    Labels            AgentLabels             `json:"labels"`
    Kind              AgentKind               `json:"kind"`
    ContextID         string                  `json:"context_id"`
    GithubContext     *AgentGithubContext     `json:"github_context,omitempty"`
    KubernetesContext *AgentKubernetesContext `json:"kubernetes_context,omitempty"`
    VanillaContext    *AgentVanillaContext    `json:"vanilla_context,omitempty"`
    NetworkPolicy     *MergedNetworkPolicy    `json:"network_policy,omitempty"`
    Active            bool                    `json:"active"`
    LastSeen          time.Time               `json:"last_seen"`
    CreatedAt         time.Time               `json:"created_at"`
    UpdatedAt         time.Time               `json:"updated_at"`
}
​
id
string
required
Unique identifier for the agent
​
project_id
string
required
Project this agent belongs to
​
os
string
required
Operating system (e.g., “linux”, “darwin”)
​
arch
string
required
Architecture (e.g., “amd64”, “arm64”)
​
hostname
string
required
Hostname of the agent machine
​
version
string
required
Agent version
​
ip
string
required
IP address of the agent
​
machine_id
string
required
Unique machine identifier
​
labels
AgentLabels
Key-value labels for filtering and organization
​
kind
AgentKind
required
Agent type: github, kubernetes, or vanilla
​
context_id
string
required
Identifier for the agent’s context
​
github_context
AgentGithubContext
GitHub Actions specific context (when kind is github)
​
kubernetes_context
AgentKubernetesContext
Kubernetes specific context (when kind is kubernetes)
​
vanilla_context
AgentVanillaContext
Vanilla agent context (when kind is vanilla)
​
network_policy
MergedNetworkPolicy
Merged network policy applicable to this agent
​
active
bool
required
Whether the agent is currently active
​
last_seen
time.Time
required
When the agent was last seen
​
created_at
time.Time
required
When the agent was created
​
updated_at
time.Time
required
When the agent was last updated

​
AgentKind

Represents the type of agent. 
type AgentKind string

const (
    AgentKindGithub     AgentKind = "github"     // GitHub Actions runner
    AgentKindKubernetes AgentKind = "kubernetes" // Kubernetes pod/node
    AgentKindVanilla    AgentKind = "vanilla"    // Standalone agent
)

​
Methods

  • String() string - Returns string representation
  • IsValid() bool - Checks if the kind is valid

​
AgentLabels

Key-value map for labeling agents. 
type AgentLabels map[string]string

​
Methods

  • Validate() error - Validates labels against defined rules
  • Encode() url.Values - Encodes labels as URL query parameters (prefixed with label.)
  • UnmarshalJSON(data []byte) error - Custom JSON unmarshaling
  • Scan(value interface{}) error - Implements sql.Scanner interface

​
Example Usage

labels := AgentLabels{
    "env": "production",
    "team": "backend",
}

// Encode to query params: ?label.env=production&label.team=backend
queryParams := labels.Encode()

​
AgentKubernetesContext

Kubernetes-specific context for agents running in K8s. 
type AgentKubernetesContext struct {
    ID        string    `json:"id"`
    Cluster   string    `json:"cluster"`
    Namespace string    `json:"namespace"`
    Node      string    `json:"node"`
    CreatedAt time.Time `json:"created_at"`
    UpdatedAt time.Time `json:"updated_at"`
}
​
id
string
required
Context identifier
​
cluster
string
required
Kubernetes cluster name
​
namespace
string
Kubernetes namespace (optional)
​
node
string
required
Kubernetes node name

​
CreateAgent

Request to create a new agent. 
type CreateAgent struct {
    OS                string                  `json:"os"`
    Arch              string                  `json:"arch"`
    Hostname          string                  `json:"hostname"`
    Version           string                  `json:"version"`
    IP                string                  `json:"ip"`
    MachineID         string                  `json:"machine_id"`
    Labels            AgentLabels             `json:"labels"`
    Kind              AgentKind               `json:"kind"`
    GithubContext     *AgentGithubContext     `json:"github_context,omitempty"`
    KubernetesContext *AgentKubernetesContext `json:"kubernetes_context,omitempty"`
    VanillaContext    *AgentVanillaContext    `json:"vanilla_context,omitempty"`
}

​
Methods

  • Validate() error - Validates all required fields and context based on agent kind
  • SetProjectID(projectID string) - Sets the project ID (populated from JWT token)
  • ProjectID() string - Returns the project ID

​
Validation Rules

  • All standard fields (os, arch, hostname, version, ip, machine_id) are required
  • kind must be a valid AgentKind
  • ip must be a valid IP address
  • Context is required and validated based on kind:
    • github kind requires GithubContext
    • kubernetes kind requires KubernetesContext
    • vanilla kind requires VanillaContext
  • Labels must pass validation

​
AgentCreated

Response after creating an agent. 
type AgentCreated struct {
    ID            string               `json:"id"`
    AgentToken    string               `json:"agent_token"`
    NetworkPolicy *MergedNetworkPolicy `json:"network_policy,omitempty"`
}
​
id
string
required
The created agent’s ID
​
agent_token
string
required
Authentication token for the agent
​
network_policy
MergedNetworkPolicy
The merged network policy applicable to this agent

​
UpdateAgent

Request to update an existing agent. 
type UpdateAgent struct {
    OS                *string                 `json:"os,omitempty"`
    Arch              *string                 `json:"arch,omitempty"`
    Hostname          *string                 `json:"hostname,omitempty"`
    Version           *string                 `json:"version,omitempty"`
    IP                *string                 `json:"ip,omitempty"`
    MachineID         *string                 `json:"machine_id,omitempty"`
    Kind              *AgentKind              `json:"kind,omitempty"`
    GithubContext     *AgentGithubContext     `json:"github_context,omitempty"`
    KubernetesContext *AgentKubernetesContext `json:"kubernetes_context,omitempty"`
    VanillaContext    *AgentVanillaContext    `json:"vanilla_context,omitempty"`
}

​
Methods

  • Validate() error - Validates update fields

​
Validation Rules

  • At least one field must be provided
  • Non-nil pointer fields cannot be empty strings
  • If kind is provided, corresponding context must also be provided
  • IP must be valid if provided

​
ListAgents

Request to list agents with filtering and pagination. 
type ListAgents struct {
    ProjectID string           `json:"project_id"`
    Active    *bool            `json:"active,omitempty"`
    OS        *string          `json:"os,omitempty"`
    Arch      *string          `json:"arch,omitempty"`
    Hostname  *string          `json:"hostname,omitempty"`
    Version   *string          `json:"version,omitempty"`
    IP        *string          `json:"ip,omitempty"`
    MachineID *string          `json:"machine_id,omitempty"`
    Kinds     []AgentKind      `json:"kinds,omitempty"`
    Labels    AgentLabels      `json:"labels,omitempty"`
    TimeStart *time.Time       `json:"time_start,omitempty"`
    TimeEnd   *time.Time       `json:"time_end,omitempty"`
    PageArgs  CursorPageArgs   `json:"page_args"`
}

​
Methods

  • Validate() error - Validates filter parameters and pagination

​
AgentsCounts

Statistics about agents. 
type AgentsCounts struct {
    Total        uint64    `json:"total"`
    Active       uint64    `json:"active"`
    Inactive     uint64    `json:"inactive"`
    CreatedSince *uint64   `json:"createdSince,omitempty"`
    At           time.Time `json:"at"`
}
​
total
uint64
required
Total number of agents
​
active
uint64
required
Number of active agents
​
inactive
uint64
required
Number of inactive agents
​
createdSince
uint64
Number of agents created since a specific time
​
at
time.Time
required
Timestamp when counts were calculated

​
Error Constants

const (
    ErrUnauthorizedAgent = errs.UnauthorizedError("permission denied")
    ErrAgentNotFound     = errs.NotFoundError("agent not found")
    ErrInvalidAgentType  = errs.InvalidArgumentError("invalid agent kind")
)

Build docs developers (and LLMs) love

Get started for freeTalk to us