instance

Documentation

Overview

Package instance tracks the state of running klausctl container instances.

Index

• func AppendSuffix(name string) (string, error)
• func Clear(paths *config.Paths) error
• func ContainerName(name string) string
• func GenerateSuffix() (string, error)
• func NewUUID() string
• type CollisionState
  • func CheckCollision(ctx context.Context, paths *config.Paths) (CollisionState, error)
• type Instance
  • func Load(paths *config.Paths) (*Instance, error)
  • func LoadAll(paths *config.Paths) ([]*Instance, error)
  • func (i *Instance) ContainerName() string
  • func (i *Instance) Save(paths *config.Paths) error

Functions

func AppendSuffix

func AppendSuffix(name string) (string, error)

AppendSuffix returns name + "-" + a random 4-char suffix.

func Clear

func Clear(paths *config.Paths) error

Clear removes the instance state file.

func ContainerName

func ContainerName(name string) string

ContainerName returns the container name for a given instance name.

func GenerateSuffix

func GenerateSuffix() (string, error)

GenerateSuffix returns a random 4-character lowercase hex string ([0-9a-f]) suitable for appending to instance names to avoid collisions.

func NewUUID

func NewUUID() string

NewUUID returns a new random UUID string for instance identification.

Types

type CollisionState

type CollisionState int

CollisionState describes the state of an existing instance that collides with a requested name.

const (
	// NoCollision means no instance with the given name exists.
	NoCollision CollisionState = iota
	// CollisionStopped means an instance directory exists but no container is running.
	CollisionStopped
	// CollisionRunning means a container for this instance is currently running.
	CollisionRunning
)

func CheckCollision

func CheckCollision(ctx context.Context, paths *config.Paths) (CollisionState, error)

CheckCollision determines whether an instance with the given name already exists and, if so, whether its container is running or stopped.

type Instance

type Instance struct {
	// UUID uniquely identifies this instance run for archiving purposes.
	UUID string `json:"uuid,omitempty"`
	// Name is the instance name (default: "default").
	Name string `json:"name"`
	// ContainerID is the container ID returned by the runtime.
	ContainerID string `json:"containerID"`
	// Runtime is the container runtime used ("docker" or "podman").
	Runtime string `json:"runtime"`
	// Personality is the OCI reference of the resolved personality (empty when none).
	Personality string `json:"personality,omitempty"`
	// Image is the container image reference.
	Image string `json:"image"`
	// Port is the host port mapped to the MCP endpoint.
	Port int `json:"port"`
	// Workspace is the host workspace directory.
	Workspace string `json:"workspace"`
	// StartedAt is when the container was started.
	StartedAt time.Time `json:"startedAt"`
}

Instance holds the state of a running klausctl container.

func Load

func Load(paths *config.Paths) (*Instance, error)

Load reads the instance state from the instance file.

func LoadAll

func LoadAll(paths *config.Paths) ([]*Instance, error)

LoadAll reads instance state files from all per-instance directories.

func (*Instance) ContainerName

func (i *Instance) ContainerName() string

ContainerName returns the container name used by the runtime.

func (*Instance) Save

func (i *Instance) Save(paths *config.Paths) error

Save writes the instance state to the instance file. The caller is responsible for setting StartedAt before calling Save.