go-container/specs/container.md

container

Import: dappco.re/go/core/container Files: 5

Types

Container

type Container struct

Represents the runtime and persisted record for a LinuxKit VM.

• ID string: An 8-character hex identifier generated by GenerateID.
• Name string: Optional human-readable container name.
• Image string: Path to the LinuxKit image file used to start the VM.
• Status Status: Current lifecycle state.
• PID int: Hypervisor process ID.
• StartedAt time.Time: VM start time.
• Ports map[int]int: Host-to-guest port mappings.
• Memory int: Memory allocation in MB.
• CPUs int: CPU allocation count.

Status

type Status string

Container lifecycle state values.

• StatusRunning: The VM is running.
• StatusStopped: The VM has stopped cleanly or was marked stopped after exit.
• StatusError: The VM exited or was tracked with an error state.

RunOptions

type RunOptions struct

Options passed to Manager.Run and LinuxKitManager.Run.

• Name string: Optional human-readable name.
• Detach bool: Starts the VM in the background when true.
• Memory int: Requested memory in MB. LinuxKitManager.Run defaults this to 1024 when unset.
• CPUs int: Requested CPU count. LinuxKitManager.Run defaults this to 1 when unset.
• Ports map[int]int: Host-to-guest port forwards.
• Volumes map[string]string: Host-to-guest 9p share mappings.
• SSHPort int: Host port forwarded to guest SSH. LinuxKitManager.Run defaults this to 2222 when unset.
• SSHKey string: Declared SSH private key path for exec operations.

Manager

type Manager interface

Abstracts container lifecycle operations for LinuxKit VMs.

• Run(ctx, image, opts): Starts a VM from an image and returns its record.
• Stop(ctx, id): Stops a VM by container ID.
• List(ctx): Returns known containers.
• Logs(ctx, id, follow): Opens the container log stream, optionally in follow mode.
• Exec(ctx, id, cmd): Runs a command inside the guest through SSH.

Hypervisor

type Hypervisor interface

Builds the process invocation used to boot a LinuxKit image.

• Name() string: Returns the hypervisor identifier.
• Available() bool: Reports whether the implementation can run on the current system.
• BuildCommand(ctx, image, opts): Produces the proc.Command used to launch the guest.

HypervisorOptions

type HypervisorOptions struct

Normalized VM launch settings handed to a Hypervisor.

• Memory int: Guest memory in MB.
• CPUs int: Guest CPU count.
• LogFile string: Log file path selected by the manager.
• SSHPort int: Host SSH forward.
• Ports map[int]int: Additional host-to-guest port forwards.
• Volumes map[string]string: Host-to-guest volume mappings.
• Detach bool: Background execution flag.

QemuHypervisor

type QemuHypervisor struct

Hypervisor implementation for QEMU.

• Binary string: Executable to run. The constructor defaults this to qemu-system-x86_64.

HyperkitHypervisor

type HyperkitHypervisor struct

Hypervisor implementation for Hyperkit on macOS.

• Binary string: Executable to run. The constructor defaults this to hyperkit.

ImageFormat

type ImageFormat string

Disk or ISO format detected from an image filename.

• FormatISO: .iso
• FormatQCOW2: .qcow2
• FormatVMDK: .vmdk
• FormatRaw: .raw or .img
• FormatUnknown: Any other extension

LinuxKitManager

type LinuxKitManager struct

Concrete Manager backed by a State, a detected or injected Hypervisor, and an io.Medium.

State

type State struct

Persistent container registry stored as JSON.

• Containers map[string]*Container: Container records keyed by ID.

Template

type Template struct

Metadata for an embedded or user-supplied LinuxKit YAML template.

• Name string: Template identifier such as core-dev.
• Description string: Human-readable description shown in template listings.
• Path string: Embedded path or on-disk path to the YAML source.

Functions

Top-Level Functions

• GenerateID() (string, error): Reads 4 random bytes and returns an 8-character hex ID.
• DetectImageFormat(path string) ImageFormat: Maps file extensions to ImageFormat values.
• DetectHypervisor() (Hypervisor, error): Prefers Hyperkit on macOS when available, otherwise tries QEMU, and errors when neither is usable.
• GetHypervisor(name string) (Hypervisor, error): Returns a named hypervisor only if the requested implementation is currently available.
• DefaultStateDir() (string, error): Resolves the state directory to ~/.core.
• DefaultStatePath() (string, error): Resolves the JSON state file path to ~/.core/containers.json.
• DefaultLogsDir() (string, error): Resolves the log directory to ~/.core/logs.
• LogPath(id string) (string, error): Resolves a container log path as <logsDir>/<id>.log.
• EnsureLogsDir() error: Creates the log directory if it does not already exist.
• NewState(filePath string) *State: Returns an empty in-memory state bound to a file path.
• LoadState(filePath string) (*State, error): Loads JSON state from disk or returns an empty state when the file does not exist.
• ListTemplates() []Template: Collects embedded templates first, then user templates from .core/linuxkit.
• ListTemplatesIter() iter.Seq[Template]: Streams the same template list lazily.
• GetTemplate(name string) (string, error): Reads an embedded template first, then a user template file named <name>.yml from the user template directory.
• ApplyTemplate(name string, vars map[string]string) (string, error): Loads a named template and applies variable substitution.
• ApplyVariables(content string, vars map[string]string) (string, error): Replaces ${VAR} and ${VAR:-default} placeholders and errors when required variables are missing.
• ExtractVariables(content string) (required []string, optional map[string]string): Returns sorted required variable names and optional variables with their defaults.

QemuHypervisor

• NewQemuHypervisor() *QemuHypervisor: Returns a QemuHypervisor configured with the default QEMU binary name.
• (*QemuHypervisor).Name() string: Returns qemu.
• (*QemuHypervisor).Available() bool: Checks for the configured binary on PATH.
• (*QemuHypervisor).BuildCommand(ctx context.Context, image string, opts *HypervisorOptions) (*proc.Command, error): Builds a QEMU command for ISO, qcow2, vmdk, or raw images, enables nographic serial output, applies user-mode networking and host port forwards, mounts 9p shares, and uses KVM or HVF acceleration when available.

HyperkitHypervisor

• NewHyperkitHypervisor() *HyperkitHypervisor: Returns a HyperkitHypervisor configured with the default Hyperkit binary name.
• (*HyperkitHypervisor).Name() string: Returns hyperkit.
• (*HyperkitHypervisor).Available() bool: Requires macOS and a hyperkit binary on PATH.
• (*HyperkitHypervisor).BuildCommand(ctx context.Context, image string, opts *HypervisorOptions) (*proc.Command, error): Builds a Hyperkit command with ACPI, serial console output, disk attachment for ISO or block images, and optional slirp TCP forwards for SSH and declared ports.

LinuxKitManager

• NewLinuxKitManager(m io.Medium) (*LinuxKitManager, error): Resolves the default state path, loads state, auto-detects a hypervisor, and returns a ready manager.
• NewLinuxKitManagerWithHypervisor(m io.Medium, state *State, hypervisor Hypervisor) *LinuxKitManager: Creates a manager around injected dependencies without auto-detection.
• (*LinuxKitManager).Run(ctx context.Context, image string, opts RunOptions) (*Container, error): Validates the image, applies defaults, creates a log file, starts the hypervisor, records the container in state, and updates status after foreground completion or detached exit.
• (*LinuxKitManager).Stop(ctx context.Context, id string) error: Sends SIGTERM to a running VM, escalates to SIGKILL after 10 seconds or on context cancellation, and persists the stopped state.
• (*LinuxKitManager).List(ctx context.Context) ([]*Container, error): Returns copies of all tracked containers and reconciles stale running entries when their process is no longer alive.
• (*LinuxKitManager).Logs(ctx context.Context, id string, follow bool) (io.ReadCloser, error): Opens the log file directly or returns a follow reader that tails new data until the context ends.
• (*LinuxKitManager).Exec(ctx context.Context, id string, cmd []string) error: Runs ssh to root@localhost on port 2222 with strict host-key checking and the shared ~/.core/known_hosts file.
• (*LinuxKitManager).State() *State: Returns the manager's state object.
• (*LinuxKitManager).Hypervisor() Hypervisor: Returns the manager's configured hypervisor.

State

• (*State).SaveState() error: Serializes the state as JSON and writes it to the configured file, creating parent directories first.
• (*State).Add(c *Container) error: Inserts a container record and persists the state.
• (*State).Get(id string) (*Container, bool): Returns a copy of the stored container to avoid caller-side data races.
• (*State).Update(c *Container) error: Replaces a container record and persists the state.
• (*State).Remove(id string) error: Deletes a container record and persists the state.
• (*State).All() []*Container: Returns copies of every stored container.
• (*State).FilePath() string: Returns the JSON file path used for persistence.