6c4050486b
Update module path from forge.lthn.ai/core/go-container to dappco.re/go/core/container. Migrate import paths for go-io (v0.2.0), go-log (v0.1.0), and go-i18n (v0.2.0) to their new dappco.re equivalents. cli and config remain at forge.lthn.ai (not yet migrated). Co-Authored-By: Virgil <virgil@lethean.io>
73 lines
2.9 KiB
Markdown
73 lines
2.9 KiB
Markdown
# go-container
|
|
|
|
Module: `dappco.re/go/core/container`
|
|
|
|
Container runtime for managing LinuxKit VMs as lightweight containers. Supports running LinuxKit images (ISO, qcow2, vmdk, raw) via QEMU or Hyperkit hypervisors. Includes a dev environment system for Claude Code agents and development workflows.
|
|
|
|
## Architecture
|
|
|
|
| File/Dir | Purpose |
|
|
|----------|---------|
|
|
| `container.go` | `Container`, `Manager` interface, `Status`, `RunOptions`, `ImageFormat` types |
|
|
| `hypervisor.go` | `Hypervisor` interface, `QemuHypervisor`, `HyperkitHypervisor`, `DetectHypervisor()` |
|
|
| `linuxkit.go` | LinuxKit image building |
|
|
| `state.go` | Container state persistence |
|
|
| `templates.go` | LinuxKit YAML template management |
|
|
| `devenv/` | Development environment: Claude agent, config, Docker, images, shell, SSH, serve, test |
|
|
| `sources/` | Image sources: CDN, GitHub, generic source interface |
|
|
| `cmd/vm/` | CLI commands: container, templates, VM management |
|
|
|
|
## Key Types
|
|
|
|
### Container Runtime
|
|
|
|
- **`Container`** — Running instance: `ID` (8 hex chars), `Name`, `Image`, `Status`, `PID`, `StartedAt`, `Ports`, `Memory`, `CPUs`
|
|
- **`Manager`** interface — `Run()`, `Stop()`, `List()`, `Logs()`, `Exec()`
|
|
- **`RunOptions`** — `Name`, `Detach`, `Memory` (MB), `CPUs`, `Ports`, `Volumes`, `SSHPort`, `SSHKey`
|
|
- **`Status`** — `StatusRunning`, `StatusStopped`, `StatusError`
|
|
- **`ImageFormat`** — `FormatISO`, `FormatQCOW2`, `FormatVMDK`, `FormatRaw`, `FormatUnknown`
|
|
|
|
### Hypervisors
|
|
|
|
- **`Hypervisor`** interface — `Name()`, `Available()`, `BuildCommand()`
|
|
- **`QemuHypervisor`** — QEMU with KVM (Linux) or HVF (macOS) acceleration, virtio networking, 9p volume shares
|
|
- **`HyperkitHypervisor`** — macOS-only Hyperkit with ACPI, virtio-blk, slirp networking
|
|
- **`HypervisorOptions`** — `Memory`, `CPUs`, `LogFile`, `SSHPort`, `Ports`, `Volumes`, `Detach`
|
|
- **`DetectHypervisor()`** — Auto-selects best available (prefers Hyperkit on macOS, falls back to QEMU)
|
|
- **`DetectImageFormat()`** — Determines format from file extension
|
|
|
|
### Dev Environment (`devenv/`)
|
|
|
|
- **Claude agent** configuration and management
|
|
- **Docker** container operations
|
|
- **Image** management (pull, build, cache)
|
|
- **Shell** access to containers
|
|
- **SSH** utilities for container access
|
|
- **Serve** — development server management
|
|
- **Test** — container-based test execution
|
|
|
|
### Image Sources (`sources/`)
|
|
|
|
- **Source** interface for fetching LinuxKit images
|
|
- **CDN source** — Download from CDN
|
|
- **GitHub source** — Download from GitHub releases
|
|
|
|
## Usage
|
|
|
|
```go
|
|
import "dappco.re/go/core/container"
|
|
|
|
// Auto-detect hypervisor
|
|
hv, _ := container.DetectHypervisor()
|
|
|
|
// Detect image format
|
|
format := container.DetectImageFormat("vm.qcow2") // FormatQCOW2
|
|
|
|
// Generate container ID
|
|
id, _ := container.GenerateID() // e.g. "a1b2c3d4"
|
|
```
|
|
|
|
## Dependencies
|
|
|
|
- No core ecosystem dependencies in root package
|
|
- `devenv/` imports SSH and Docker tooling
|