cfg

package
v0.8.2 Latest Latest
Warning

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

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

Documentation

Index

Constants

View Source 
const DefaultRegistry = "ghcr.io/devcell-sh/devcell"

DefaultRegistry is the default container registry for devcell images. Must match runner.DefaultRegistry.

Variables

This section is empty.

Functions

func ApplyEnv 

func ApplyEnv(c *CellConfig, getenv func(string) string)

ApplyEnv overrides scalar fields from environment variables.

func KnownStacks added in v0.4.0 

func KnownStacks() []string

KnownStacks returns the list of valid stack names.

func StackSize added in v0.4.0 

func StackSize(stack string) (string, bool)

StackSize returns the approximate download size for the given stack.

func ValidateModulesAgainstCatalog added in v0.8.0 

func ValidateModulesAgainstCatalog(userModules, catalogNames []string) error

ValidateModulesAgainstCatalog checks that every name in `userModules` exists in `catalogNames`. Returns nil on success, or a user-friendly error listing all unknown names and the available catalog for hinting.

Used by the CLI at TOML-parse time to catch typos like `yahoo-finanace` before the nix subprocess gets invoked.

func ValidateStack added in v0.4.0 

func ValidateStack(stack string) error

ValidateStack checks that stack is a known stack name. Empty is valid (defaults to ultimate).

Types

type AwsSection added in v0.4.0 

type AwsSection struct {
	ReadOnly *bool `toml:"read_only"` // default: true (nil = not set → true)
}

AwsSection holds [aws] config for AWS credential scoping.

func (AwsSection) ResolvedReadOnly added in v0.4.0 

func (a AwsSection) ResolvedReadOnly() bool

ResolvedReadOnly returns false unless explicitly set to true.

type CellConfig 

type CellConfig struct {
	Cell     CellSection
	LLM      LLMSection     `toml:"llm"`
	Git      GitSection     `toml:"git"`
	Ports    PortsSection   `toml:"ports"`
	Op       OpSection      `toml:"op"`
	Aws      AwsSection     `toml:"aws"`
	Stealth  StealthSection `toml:"stealth"`
	Env      map[string]string
	Mise     map[string]string `toml:"mise"` // [mise] — keys map to MISE_<UPPER_KEY> env vars
	Volumes  []VolumeMount
	Packages PackagesSection
}

CellConfig is the merged configuration from all TOML layers.

func LoadFile 

func LoadFile(path string) (CellConfig, error)

LoadFile parses a TOML file into CellConfig. Returns zero value + nil error if the file does not exist.

func LoadFromOS 

func LoadFromOS(configDir, cwd string) CellConfig

LoadFromOS loads the layered config using real XDG paths and os.Getenv.

func LoadLayered 

func LoadLayered(globalPath, projectPath string, getenv func(string) string) CellConfig

LoadLayered loads global + project files, merges them, then applies env overrides.

func Merge 

func Merge(global, project CellConfig) CellConfig

Merge returns a new CellConfig with project overriding global for scalars; slices accumulate (Volumes, Ports.Forward, Op documents, [cell].modules). For [cell].modules: explicit empty list in project ([]) clears global as escape hatch; otherwise project values are unioned with global, deduped.

type CellSection 

type CellSection struct {
	ImageTag         string   `toml:"image_tag"`
	Registry         string   `toml:"registry"`          // container registry; default: DefaultRegistry; env: DEVCELL_REGISTRY
	GUI              *bool    `toml:"gui"`               // default: true (nil = not set → true)
	Timezone         string   `toml:"timezone"`          // IANA tz (e.g. "Europe/Prague"); default: host $TZ
	Locale           string   `toml:"locale"`            // POSIX locale (e.g. "en_US.UTF-8"); default: "en_US.UTF-8"
	Stack            string   `toml:"stack"`             // nix stack name (e.g. "go", "python"); default: "base" (see ResolvedStack)
	Modules          []string `toml:"modules"`           // extra nix modules to compose on top of stack
	NixhomePath      string   `toml:"nixhome"`           // local nixhome path; overridden by DEVCELL_NIXHOME_PATH env
	Engine           string   `toml:"engine"`            // execution engine: "docker" (default) or "vagrant"
	VagrantProvider  string   `toml:"vagrant_provider"`  // vagrant provider: "utm" (default) or "libvirt"
	VagrantBox       string   `toml:"vagrant_box"`       // vagrant box name override (default: "utm/bookworm")
	DockerPrivileged bool     `toml:"docker_privileged"` // run container with --privileged; default: false
	PerCellImage     *bool    `toml:"per_cell_image"`    // tag user image per cell instead of per stack; default: false
	Hostname         string   `toml:"hostname"`          // override container hostname; default: computed "cell-<basename>-<bunk>"; env: DEVCELL_HOSTNAME
	MacAddress       string   `toml:"mac_address"`       // MAC for the container's NIC (XX:XX:XX:XX:XX:XX); pinned across restarts for infra-side identity persistence. Honored on user-defined bridge networks (devcell uses --network devcell-network). Empty → docker auto-assigns a random MAC per launch.
	Thin             *bool    `toml:"thin"`              // thin image mode; default: true; disable with thin=false or DEVCELL_THIN=0
}

CellSection holds [cell] config.

func (CellSection) DescribeModulesSource added in v0.8.0 

func (c CellSection) DescribeModulesSource() string

DescribeModulesSource classifies how the effective module set is sourced — stack-only, explicit-modules-only, both merged, or default — so the cell startup banner can tell the user at a glance what's about to load (CELL-48). 

default (base stack, no extra modules)  // neither set
stack=<name>                            // only stack
modules=[a,b,c]                         // only explicit modules
stack=<name> + modules=[a,b,c] (merged) // both

func (CellSection) ResolvedGUI added in v0.4.0 

func (c CellSection) ResolvedGUI() bool

ResolvedGUI returns the effective GUI setting: true unless explicitly set to false.

func (CellSection) ResolvedHostname added in v0.7.0 

func (c CellSection) ResolvedHostname(computed string) string

ResolvedHostname returns the effective container hostname. Precedence: DEVCELL_HOSTNAME env > [cell] hostname in TOML > computed default (typically "cell-<basename>-<bunk>" assembled by config.Load).

func (CellSection) ResolvedPerCellImage added in v0.8.0 

func (c CellSection) ResolvedPerCellImage() bool

ResolvedPerCellImage returns true only when explicitly enabled.

func (CellSection) ResolvedRegistry added in v0.4.0 

func (c CellSection) ResolvedRegistry() string

ResolvedRegistry returns the effective registry: env > toml > default.

func (CellSection) ResolvedStack added in v0.4.0 

func (c CellSection) ResolvedStack() string

ResolvedStack returns Stack if set, else "base".

func (CellSection) ResolvedThin added in v0.8.0 

func (c CellSection) ResolvedThin() bool

ResolvedThin returns the effective thin setting: default ON, disabled by env/toml.

func (CellSection) StackExplicit added in v0.8.0 

func (c CellSection) StackExplicit() bool

StackExplicit reports whether the user opted into a specific stack via TOML (`[cell] stack = "..."`). Drives the build progress label — when false, the "stack=..." qualifier is suppressed (CELL-43). CLI/env overrides are handled at the call site by OR'ing the override into this flag.

type GitSection added in v0.3.0 

type GitSection struct {
	AuthorName     string `toml:"author_name"`
	AuthorEmail    string `toml:"author_email"`
	CommitterName  string `toml:"committer_name"`
	CommitterEmail string `toml:"committer_email"`
}

GitSection holds [git] config for git identity inside the container.

func (GitSection) HasIdentity added in v0.3.0 

func (g GitSection) HasIdentity() bool

HasIdentity reports whether any git identity field is set.

func (GitSection) ResolvedCommitterEmail added in v0.3.0 

func (g GitSection) ResolvedCommitterEmail() string

ResolvedCommitterEmail returns CommitterEmail if set, else falls back to AuthorEmail.

func (GitSection) ResolvedCommitterName added in v0.3.0 

func (g GitSection) ResolvedCommitterName() string

ResolvedCommitterName returns CommitterName if set, else falls back to AuthorName.

type LLMModelsSection added in v0.3.0 

type LLMModelsSection struct {
	Default   string                 `toml:"default"`
	Providers map[string]LLMProvider `toml:"providers"`
}

LLMModelsSection holds [llm.models] config — provider/model declarations.

type LLMProvider added in v0.2.0 

type LLMProvider struct {
	BaseURL string   `toml:"base_url"`
	Models  []string `toml:"models"`
}

LLMProvider holds a single provider entry under [llm.models.providers.<name>].

type LLMSection added in v0.3.0 

type LLMSection struct {
	SystemPrompt     string           `toml:"system_prompt"`
	SystemPromptFile string           `toml:"system_prompt_file"`
	UseOllama        bool             `toml:"use_ollama"`
	Models           LLMModelsSection `toml:"models"`
}

LLMSection holds [llm] config — all AI agent settings in one place.

SystemPrompt and SystemPromptFile are mutually exclusive — set one or neither. The resolver in internal/runner.ResolveSystemPrompt validates this and returns an error when both are set, so we don't fail config load for projects where the conflict is harmless (e.g. callers that don't read system prompts).

type MissingEnvError added in v0.8.0 

type MissingEnvError struct {
	// Refs maps each missing host var name to the [env].<key> paths that
	// referenced it (the same var may be referenced from multiple [env] keys).
	Refs map[string][]string
}

MissingEnvError reports host env vars referenced from .devcell.toml [env] values that are unset (or empty) on the host. Aggregates all misses so the user fixes them in one pass rather than one boot per typo.

func ExpandEnv added in v0.8.0 

func ExpandEnv(env map[string]string, lookup func(string) (string, bool)) *MissingEnvError

ExpandEnv resolves ${VAR} and $VAR in [env] values against the host environment via lookup (pass os.LookupEnv in production). Values are mutated in place. Returns a non-nil *MissingEnvError if any reference resolved to an unset or empty host var — set-but-empty is treated as a miss (almost always a config bug).

Plain values (no `$`) pass through unchanged and never allocate.

func (*MissingEnvError) Error added in v0.8.0 

func (e *MissingEnvError) Error() string

type OpSection added in v0.3.0 

type OpSection struct {
	Documents []string `toml:"documents"` // 1Password document names to resolve via `op item get`
	Items     []string `toml:"items"`     // deprecated: use documents (kept for backwards compat)
}

OpSection holds [op] config for 1Password secret injection.

func (OpSection) ResolvedDocuments added in v0.4.0 

func (o OpSection) ResolvedDocuments() []string

ResolvedDocuments returns the merged list of documents + legacy items (deduped).

type PackagesSection 

type PackagesSection struct {
	Npm    map[string]string `toml:"npm"`
	Python map[string]string `toml:"python"`
}

PackagesSection holds [packages] config for npm and python tools.

type PortsSection added in v0.4.0 

type PortsSection struct {
	Forward   []string `toml:"forward"`    // port mappings: "3000", "8080:3000"
	PublishIP string   `toml:"publish_ip"` // host interface for `docker run -p`; default "0.0.0.0". Applies to VNC, RDP, and all forward entries.
}

PortsSection holds [ports] config for port forwarding.

func (PortsSection) ResolvedPublishIP added in v0.7.0 

func (p PortsSection) ResolvedPublishIP() string

ResolvedPublishIP returns the effective host IP for `docker run -p`. Defaults to "0.0.0.0" when unset so cells are reachable from other hosts regardless of dockerd's bind default (some Docker Desktop / rootless setups default to 127.0.0.1, which would silently break remote RDP/VNC). Override in TOML to bind a specific NIC or "127.0.0.1" for loopback-only.

type StealthSection added in v0.8.0 

type StealthSection struct {
	Arch     string `toml:"arch"`
	Platform string `toml:"platform"`
}

StealthSection holds [stealth] config for browser fingerprint spoofing.

func (StealthSection) ResolvedArch added in v0.8.0 

func (s StealthSection) ResolvedArch() string

ResolvedArch returns the stealth architecture: explicit > host-detected. Maps runtime.GOARCH to Chrome's getHighEntropyValues().architecture values.

func (StealthSection) ResolvedPlatform added in v0.8.0 

func (s StealthSection) ResolvedPlatform() string

ResolvedPlatform returns the stealth platform: explicit > "Linux" default.

func (StealthSection) ResolvedUserAgent added in v0.8.0 

func (s StealthSection) ResolvedUserAgent() string

ResolvedUserAgent builds a Chrome UA string matching the stealth identity.

type VolumeMount 

type VolumeMount struct {
	Mount string `toml:"mount"`
}

VolumeMount holds a single [[volumes]] entry.

func (VolumeMount) Resolved added in v0.8.1 

func (v VolumeMount) Resolved() string

Resolved returns the mount string in `host:container[:mode]` form, expanding the single-path shorthand where a colonless value means "mount this path at the same path inside the container".

Examples: 

"/foo/bar"          → "/foo/bar:/foo/bar"
"/foo:/bar"         → "/foo:/bar"      (unchanged)
"/foo:/bar:ro"      → "/foo:/bar:ro"   (unchanged)

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.