Documentation
¶
Overview ¶
Package agent provides the Agent interface and utilities for AI agent setup in cloister containers. Each agent (Claude, Codex, Gemini CLI, etc.) implements the Agent interface to handle its specific configuration needs.
Index ¶
- Constants
- Variables
- func AppendBashAlias(containerName, aliasLine string) error
- func CopyDirToContainer(containerName, dirName string, excludePatterns []string, ...) error
- func GetContainerEnvVars(a Agent, agentCfg *config.AgentConfig) (map[string]string, error)
- func List() []string
- func MergeJSONConfig(hostFileName string, fieldsToCopy []string, ...) (string, error)
- func MergeTOMLConfig(hostFileName string, _ []string, forcedValues map[string]any) (string, error)
- func Register(agent Agent)
- func WriteFileToContainer(containerName, destPath, content string) error
- type Agent
- type ClaudeAgent
- type CodexAgent
- type ContainerEnvProvider
- type SetupResult
Constants ¶
const ContainerGID = "1000"
ContainerGID is the GID of the cloister user inside containers.
const ContainerUID = "1000"
ContainerUID is the UID of the cloister user inside containers.
Variables ¶
var UserHomeDirFunc = os.UserHomeDir
UserHomeDirFunc returns the user's home directory. Can be overridden in tests to use a mock home directory.
Functions ¶
func AppendBashAlias ¶
AppendBashAlias adds an alias line to the container's bashrc. The alias is only added if not already present (idempotent). The container must be running.
func CopyDirToContainer ¶
func CopyDirToContainer(containerName, dirName string, excludePatterns []string, transforms ...func(tmpDir string) error) error
CopyDirToContainer copies a directory from the host to the container. The directory is copied to containerHomeDir (e.g., ~/.claude -> /home/cloister/.claude).
Parameters:
- containerName: the Docker container name
- dirName: the directory name under $HOME (e.g., ".claude")
- excludePatterns: patterns to exclude (passed to rsync --exclude)
- transforms: optional functions applied to the staging directory after rsync but before copying to the container. Each transform receives the path to the staged directory (e.g., /tmp/cloister-settings-xxx/.claude).
Symlinks are dereferenced during copy so that settings stored in dotfiles repositories work correctly inside the container.
Returns nil if the directory doesn't exist on the host (not an error). Returns an error only if the directory exists but cannot be copied.
func GetContainerEnvVars ¶
GetContainerEnvVars returns container env vars for an agent if it implements ContainerEnvProvider. Returns nil if the agent doesn't implement the interface or if no env vars are needed.
func MergeJSONConfig ¶
func MergeJSONConfig(hostFileName string, fieldsToCopy []string, forcedValues, conditionalCopy map[string]any) (string, error)
MergeJSONConfig reads a JSON config file from the host, copies specified fields, applies forced values, and returns the merged JSON.
Parameters:
- hostFileName: the config file name under $HOME (e.g., ".claude.json")
- fieldsToCopy: top-level fields to copy from host config
- forcedValues: fields that are always set to specific values (override host)
- conditionalCopy: additional fields to copy from host (e.g., auth-method-specific)
Returns the merged JSON as an indented string with a trailing newline. If the host file doesn't exist, only forcedValues are included.
func MergeTOMLConfig ¶
MergeTOMLConfig reads a TOML config file from the host and appends forced values. This is a simple implementation that copies the existing config and appends cloister-specific overrides at the end (TOML allows later values to override earlier ones).
Parameters:
- hostFileName: the config file path under $HOME (e.g., ".codex/config.toml")
- fieldsToCopy: unused (reserved for future use, can be nil)
- forcedValues: fields that are always set to specific values (override host) Keys can use dot notation for nested values (e.g., "sandbox_workspace_write.network_access")
Returns the merged TOML as a string. If the host file doesn't exist, only forcedValues are included.
func Register ¶
func Register(agent Agent)
Register adds an agent to the registry. This is typically called from init() in agent implementation files.
func WriteFileToContainer ¶
WriteFileToContainer writes a file to the container with proper ownership.
Parameters:
- containerName: the Docker container name
- destPath: absolute path in the container (e.g., "/home/cloister/.claude.json")
- content: the file content to write
Types ¶
type Agent ¶
type Agent interface {
// Name returns the agent identifier (e.g., "claude", "codex").
// This is used for config lookups and logging.
Name() string
// Setup performs all agent-specific container setup.
// This is called after the container is created and started, but before
// the user attaches to it. The implementation should:
// - Copy settings directories if needed
// - Generate config files if needed
// - Inject credentials if needed
//
// The agentCfg parameter contains the agent configuration from the global
// config file. It may be nil if no config exists for this agent.
//
// Returns a SetupResult containing env vars to set, or an error if setup fails.
Setup(containerName string, agentCfg *config.AgentConfig) (*SetupResult, error)
}
Agent defines the interface for AI agent setup in containers. Each agent implementation handles its specific configuration needs (settings directories, config files, credentials, etc.).
type ClaudeAgent ¶
type ClaudeAgent struct {
// Injector handles credential extraction and injection.
// If nil, claude.NewInjector() is used.
Injector *claude.Injector
}
ClaudeAgent handles setup for Claude Code in containers.
func NewClaudeAgent ¶
func NewClaudeAgent() *ClaudeAgent
NewClaudeAgent creates a new ClaudeAgent with default dependencies.
func (*ClaudeAgent) GetContainerEnvVars ¶
func (a *ClaudeAgent) GetContainerEnvVars(agentCfg *config.AgentConfig) (map[string]string, error)
GetContainerEnvVars implements ContainerEnvProvider. It always returns CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 to prevent the plugin auto-updater from breaking in network-isolated containers. If AuthMethod is configured, credential env vars are included as well.
func (*ClaudeAgent) Setup ¶
func (a *ClaudeAgent) Setup(containerName string, agentCfg *config.AgentConfig) (*SetupResult, error)
Setup performs Claude-specific container setup. This copies the ~/.claude/ settings directory, injects credentials, and generates the ~/.claude.json config file.
type CodexAgent ¶
type CodexAgent struct {
// Injector handles credential extraction and injection.
// If nil, codex.NewInjector() is used.
Injector *codex.Injector
}
CodexAgent handles setup for Codex CLI in containers.
func NewCodexAgent ¶
func NewCodexAgent() *CodexAgent
NewCodexAgent creates a new CodexAgent with default dependencies.
func (*CodexAgent) GetContainerEnvVars ¶
func (a *CodexAgent) GetContainerEnvVars(agentCfg *config.AgentConfig) (map[string]string, error)
GetContainerEnvVars implements ContainerEnvProvider. It returns credential env vars without requiring a running container.
func (*CodexAgent) Setup ¶
func (a *CodexAgent) Setup(containerName string, agentCfg *config.AgentConfig) (*SetupResult, error)
Setup performs Codex-specific container setup. This copies the ~/.codex/ settings directory, injects credentials, generates the config.toml, and appends cloister rules to AGENTS.md.
type ContainerEnvProvider ¶
type ContainerEnvProvider interface {
// GetContainerEnvVars returns environment variables needed for the container.
// This includes both credential env vars and agent-specific operational env vars.
// This is called before container creation and must not require a running container.
// Returns nil map and nil error if no env vars are needed.
GetContainerEnvVars(agentCfg *config.AgentConfig) (map[string]string, error)
}
ContainerEnvProvider is an optional interface that agents can implement to provide environment variables before the container is created. This is necessary because env vars must be set at container creation time, but Setup() runs after the container starts.
type SetupResult ¶
type SetupResult struct {
// EnvVars contains environment variables to set in the container.
// Keys are variable names, values are the variable values.
EnvVars map[string]string
}
SetupResult contains the results of agent setup that the orchestration code needs to configure the container.
Source Files