Documentation
¶
Index ¶
- Constants
- func AbsolutePath(parentDir, relOrAbsPath string) (string, error)
- func AbsolutePaths(parentDir string, relOrAbsPaths []string) ([]string, error)
- func ConfigEnvFilePath() string
- func Expand(ctx context.Context, value string, env Provider) (string, error)
- func ExpandAll(ctx context.Context, values []string, env Provider) ([]string, error)
- func InSandbox() bool
- func IsTrustedDockerURL(rawURL string) bool
- func Refs(value string) []string
- func SandboxTokensFilePath(dir string) string
- func SecretSourcesHelp(exampleVar string) string
- func ToValues(envMap map[string]string) []string
- type CredentialHelperProvider
- type DockerDesktopProvider
- type EnvFileStore
- type EnvFilesProvider
- type EnvListProvider
- type KeyValuePair
- type KeychainNotAvailableError
- type KeychainProvider
- type KeychainStore
- type MapEnvProvider
- type MultiProvider
- type NoEnvProvider
- type OnePasswordNotAvailableError
- type OnePasswordProvider
- type OsEnvProvider
- type PassNotAvailableError
- type PassProvider
- type PassStore
- type Provider
- type RequiredEnvError
- type RunSecretsProvider
- type SandboxTokenProvider
- type SandboxTokenWriter
- type SecretStore
- type Source
Constants ¶
const ( DockerDesktopEmail = "DOCKER_EMAIL" DockerDesktopUsername = "DOCKER_USERNAME" DockerDesktopTokenEnv = "DOCKER_TOKEN" )
const ModelSetupDocsURL = "https://docs.docker.com/ai/docker-agent/getting-started/set-up-a-model/"
ModelSetupDocsURL is the step-by-step tutorial for making a model available, covering both the cloud API-key path and the local Docker Model Runner path.
const SandboxTokensFileName = "sandbox-tokens.json"
SandboxTokensFileName is the name of the JSON file used to forward short-lived tokens (e.g. DOCKER_TOKEN) from the host into a Docker sandbox. The host writes this file periodically; the sandbox reads it.
const SecretsDocsURL = "https://docs.docker.com/ai/docker-agent/guides/secrets/"
SecretsDocsURL is the documentation page describing every built-in secret source and how to configure it.
Variables ¶
This section is empty.
Functions ¶
func AbsolutePath ¶
func ConfigEnvFilePath ¶ added in v1.101.0
func ConfigEnvFilePath() string
ConfigEnvFilePath returns the path of the env file that the default secret sources read: <config dir>/.env (e.g. ~/.config/cagent/.env).
func InSandbox ¶
func InSandbox() bool
InSandbox reports whether docker agent is running inside a Docker sandbox. Detection relies on the SANDBOX_VM_ID environment variable that Docker Desktop sets in every sandbox VM.
func IsTrustedDockerURL ¶ added in v1.78.0
IsTrustedDockerURL checks if the URL targets a domain trusted to receive the Docker Desktop JWT. It matches:
- "docker.com" and any subdomain (e.g. "desktop.docker.com") over HTTPS only
- localhost addresses ("localhost", "127.0.0.1", "::1") over HTTP or HTTPS
It performs strict hostname and scheme validation to prevent token leakage.
func Refs ¶ added in v1.92.0
Refs returns the names of the environment variables referenced by value using the same ${env.X} / ${X} syntax Expand resolves, in first-seen order and de-duplicated. It lets callers discover which variables a config field requires (e.g. for an up-front "missing env var" check) without resolving them. A value with no references yields nil.
func SandboxTokensFilePath ¶
SandboxTokensFilePath returns the absolute path to the sandbox tokens file inside the given directory.
func SecretSourcesHelp ¶ added in v1.100.0
SecretSourcesHelp returns guidance naming the built-in secret sources able to supply arbitrary variables, with a one-line example for the given variable and a link to the docs. Docker Desktop and the credential helper are deliberately absent: they only resolve fixed Docker variables (DOCKER_TOKEN, ...) and can never satisfy the keys reported missing here. Shared by the errors that report missing credentials so the advice never drifts between them.
Types ¶
type CredentialHelperProvider ¶
type CredentialHelperProvider struct {
// contains filtered or unexported fields
}
CredentialHelperProvider retrieves Docker credentials using an external CLI command configured in the user's global config file.
func NewCredentialHelperProvider ¶
func NewCredentialHelperProvider(command string, args ...string) *CredentialHelperProvider
NewCredentialHelperProvider creates a new CredentialHelperProvider instance. The command parameter is the shell command to execute to retrieve the Docker token.
type DockerDesktopProvider ¶
type DockerDesktopProvider struct{}
func NewDockerDesktopProvider ¶
func NewDockerDesktopProvider() *DockerDesktopProvider
type EnvFileStore ¶ added in v1.101.0
type EnvFileStore struct {
// contains filtered or unexported fields
}
EnvFileStore stores secrets as KEY=value lines in an env file. The file at ConfigEnvFilePath is read by the default source chain, so values stored there resolve on every later run without extra flags.
func NewConfigEnvFileStore ¶ added in v1.101.0
func NewConfigEnvFileStore() *EnvFileStore
NewConfigEnvFileStore creates an EnvFileStore writing to the docker agent config env file (see ConfigEnvFilePath).
func (*EnvFileStore) Description ¶ added in v1.101.0
func (s *EnvFileStore) Description() string
func (*EnvFileStore) Name ¶ added in v1.101.0
func (s *EnvFileStore) Name() string
func (*EnvFileStore) Store ¶ added in v1.101.0
func (s *EnvFileStore) Store(_ context.Context, name, value string) error
Store writes NAME=value to the env file, replacing the line for an existing NAME and preserving every other line (comments included). The file is created private (0600) in a private directory and written atomically.
type EnvFilesProvider ¶
type EnvFilesProvider struct {
// contains filtered or unexported fields
}
EnvFilesProvider provides access env files.
func NewEnvFilesProvider ¶
func NewEnvFilesProvider(absEnvFiles []string) (*EnvFilesProvider, error)
type EnvListProvider ¶
type EnvListProvider struct {
// contains filtered or unexported fields
}
EnvListProvider provides access a list of environment variables.
func NewEnvListProvider ¶
func NewEnvListProvider(env []string) *EnvListProvider
type KeyValuePair ¶
func ReadEnvFile ¶
func ReadEnvFile(absolutePath string) ([]KeyValuePair, error)
func ReadEnvFiles ¶
func ReadEnvFiles(absolutePaths []string) ([]KeyValuePair, error)
type KeychainNotAvailableError ¶
type KeychainNotAvailableError struct{}
func (KeychainNotAvailableError) Error ¶
func (KeychainNotAvailableError) Error() string
type KeychainProvider ¶
type KeychainProvider struct {
// contains filtered or unexported fields
}
KeychainProvider is a provider that retrieves secrets using the macOS keychain via the `security` command-line tool.
func NewKeychainProvider ¶
func NewKeychainProvider() (*KeychainProvider, error)
NewKeychainProvider creates a new KeychainProvider instance. It verifies that the `security` command is available on the system and stores the resolved absolute path for later use.
type KeychainStore ¶ added in v1.101.0
type KeychainStore struct {
// contains filtered or unexported fields
}
KeychainStore stores secrets as generic passwords in the macOS keychain, where KeychainProvider resolves them.
func NewKeychainStore ¶ added in v1.101.0
func NewKeychainStore() (*KeychainStore, error)
NewKeychainStore creates a KeychainStore. It verifies that the `security` command is available and stores the resolved absolute path.
func (*KeychainStore) Description ¶ added in v1.101.0
func (s *KeychainStore) Description() string
func (*KeychainStore) Name ¶ added in v1.101.0
func (s *KeychainStore) Name() string
func (*KeychainStore) Store ¶ added in v1.101.0
func (s *KeychainStore) Store(ctx context.Context, name, value string) error
Store writes the secret with `security -i` so the value travels over stdin and never appears in the process argument list. The fixed account name keeps -U updating the same item on re-runs (a different account would create a duplicate item instead); KeychainProvider looks up by service name only, so the account value never affects reads.
type MapEnvProvider ¶ added in v1.30.1
type MapEnvProvider struct {
// contains filtered or unexported fields
}
MapEnvProvider provides access to a static map of environment variables.
func NewMapEnvProvider ¶ added in v1.30.1
func NewMapEnvProvider(vars map[string]string) *MapEnvProvider
type MultiProvider ¶
type MultiProvider struct {
// contains filtered or unexported fields
}
func NewMultiProvider ¶
func NewMultiProvider(providers ...Provider) *MultiProvider
type NoEnvProvider ¶ added in v1.30.1
type NoEnvProvider struct{}
NoEnvProvider is a provider that never finds any variable.
func NewNoEnvProvider ¶ added in v1.30.1
func NewNoEnvProvider() *NoEnvProvider
type OnePasswordNotAvailableError ¶ added in v1.74.0
type OnePasswordNotAvailableError struct{}
func (OnePasswordNotAvailableError) Error ¶ added in v1.74.0
func (OnePasswordNotAvailableError) Error() string
type OnePasswordProvider ¶ added in v1.74.0
type OnePasswordProvider struct {
// contains filtered or unexported fields
}
OnePasswordProvider decorates another Provider and resolves 1Password secret references. When the wrapped provider returns a value starting with "op://", the value is treated as a secret reference and resolved using the `op read` CLI command. All other values are passed through unchanged.
type OsEnvProvider ¶
type OsEnvProvider struct{}
OsEnvProvider provides access to the operating system's environment variables.
func NewOsEnvProvider ¶
func NewOsEnvProvider() *OsEnvProvider
type PassNotAvailableError ¶
type PassNotAvailableError struct{}
func (PassNotAvailableError) Error ¶
func (PassNotAvailableError) Error() string
type PassProvider ¶
type PassProvider struct {
// contains filtered or unexported fields
}
PassProvider is a provider that retrieves secrets using the `pass` password manager.
func NewPassProvider ¶
func NewPassProvider() (*PassProvider, error)
NewPassProvider creates a new PassProvider instance. It verifies that `pass` is available and stores the resolved absolute path.
type PassStore ¶ added in v1.101.0
type PassStore struct {
// contains filtered or unexported fields
}
PassStore stores secrets in the `pass` password manager, where PassProvider resolves them.
func NewPassStore ¶ added in v1.101.0
NewPassStore creates a PassStore. It verifies that `pass` is available and stores the resolved absolute path.
func (*PassStore) Description ¶ added in v1.101.0
type Provider ¶
type Provider interface {
// Get retrieves the value of an environment variable by name.
// Returns (value, true) if found (value may be empty).
// Returns ("", false) if not found.
Get(ctx context.Context, name string) (string, bool)
}
func NewDefaultProvider ¶
func NewDefaultProvider() Provider
NewDefaultProvider creates a provider chain from DefaultSources. The whole chain is wrapped so that values shaped like "op://..." are resolved as 1Password secret references through the `op` CLI.
func NewOnePasswordProvider ¶ added in v1.74.0
NewOnePasswordProvider wraps provider so that "op://" references are resolved with the `op` CLI. The `op` binary is looked up lazily, only when a reference is actually encountered, so an "op://" value is never silently passed through as if it were a real secret.
type RequiredEnvError ¶
type RequiredEnvError struct {
Missing []string
// MissingModelCredentials reports whether at least one missing variable is
// a model-provider credential, in which case the error also suggests
// running a local model instead of configuring an API key.
MissingModelCredentials bool
}
func (*RequiredEnvError) Error ¶
func (e *RequiredEnvError) Error() string
type RunSecretsProvider ¶
type RunSecretsProvider struct {
// contains filtered or unexported fields
}
func NewRunSecretsProvider ¶
func NewRunSecretsProvider() *RunSecretsProvider
func (*RunSecretsProvider) Get ¶
Get reads the named secret file from the provider's root directory.
Lookups are anchored to root via os.OpenRoot: name components that escape via ".." segments, absolute paths, or symbolic links pointing outside the root are rejected by the kernel and surface as a missed lookup. An attacker who can plant a symlink under root therefore cannot coerce the agent into reading files elsewhere on the host.
type SandboxTokenProvider ¶
type SandboxTokenProvider struct {
// contains filtered or unexported fields
}
SandboxTokenProvider reads DOCKER_TOKEN from a JSON file on disk. It is used inside the sandbox where Docker Desktop's backend API is unreachable and the OS env contains only a stale one-shot token.
Only DOCKER_TOKEN is served; requests for any other variable return ("", false).
func NewSandboxTokenProvider ¶
func NewSandboxTokenProvider(path string) *SandboxTokenProvider
NewSandboxTokenProvider creates a provider that reads tokens from path.
type SandboxTokenWriter ¶
type SandboxTokenWriter struct {
// contains filtered or unexported fields
}
SandboxTokenWriter periodically fetches DOCKER_TOKEN from a provider and writes it to the sandbox tokens JSON file so that processes inside the sandbox can read a fresh value.
func NewSandboxTokenWriter ¶
func NewSandboxTokenWriter(path string, provider Provider, interval time.Duration) *SandboxTokenWriter
NewSandboxTokenWriter creates a writer that refreshes the token file at the given interval. Call SandboxTokenWriter.Start to begin writing and SandboxTokenWriter.Stop to terminate the background goroutine.
func (*SandboxTokenWriter) Start ¶
func (w *SandboxTokenWriter) Start(ctx context.Context)
Start writes the token file immediately and then refreshes it on the configured interval in a background goroutine.
func (*SandboxTokenWriter) Stop ¶
func (w *SandboxTokenWriter) Stop()
Stop terminates the background goroutine and removes the token file.
type SecretStore ¶ added in v1.101.0
type SecretStore interface {
// Name identifies the matching read-side source (e.g. "keychain").
Name() string
// Description is a short human-readable label for interactive pickers.
Description() string
// Store persists value under name, replacing any previous value.
Store(ctx context.Context, name, value string) error
}
SecretStore persists a secret so that one of the default secret sources (DefaultSources) can resolve it on later runs. Implementations are the write-side counterparts of the read-side providers: a value stored under a name must be returned by the matching provider's Get for that same name.
func SecretStores ¶ added in v1.101.0
func SecretStores() []SecretStore
SecretStores returns the secret stores usable on this machine, most preferred first: the OS-native store when its tooling is available (macOS Keychain, pass elsewhere), then the docker agent env file, which is always available as a plain-file fallback.
type Source ¶ added in v1.100.0
Source is a labeled secret source in the default provider chain. The name identifies where a value comes from (e.g. "environment", "keychain") so diagnostic commands like `docker agent doctor` can report it.
func DefaultSources ¶ added in v1.100.0
func DefaultSources() []Source
DefaultSources returns the ordered, labeled secret sources that make up the default provider chain: OS env, run secrets, the docker agent env file (<config dir>/.env, when present), credential helper (if configured), Docker Desktop, pass, and keychain. Lookup precedence is the slice order.
When running inside a Docker sandbox (detected via SANDBOX_VM_ID), a SandboxTokenProvider is prepended so that DOCKER_TOKEN is read from the JSON file written by the host-side token writer.
Source Files