Apple Container TUI

Keyboard-first terminal UI for managing Apple Container on macOS.

Overview

Apple Container TUI (actui) lets you list, start, stop, delete, and export containers; manage Apple Container machines and local Kubernetes clusters; pull and build images; browse registries; and control the daemon. State-changing actions use command previews, while destructive actions require explicit confirmation.

This repository is a proof-of-concept showcasing spec-kit, a structured AI-assisted development workflow. Full process notes are published on www.msbiro.net.

Features

• Container list with action submenus (start / stop / logs / shell / export)
• Apple Container 1.0 machine management (M) — list, create, inspect, logs, start/stop, edit resources, set default, delete
• Local Kubernetes cluster management (k) — list, create, start, delete, load images, write kubeconfig
• Safe delete with type-to-confirm
• Image management (i) — list, pull, build, prune, inspect, delete
• Dedicated registries view (g)
• Build form with --pull toggle (enabled by default)
• Daemon start/stop with structured status (running / stopped / unknown)
• Command preview before every execution
• Dry-run mode for safe practice
• JSONL command logs with rotation

Quick Start

Prerequisites

• macOS 26.x on Apple Silicon
• Apple Container CLI 1.0+ installed and in PATH
• Go 1.24+ if building from source

Verify the CLI is available:

container system version

Machine workflows require the Apple Container service to be running:

container system start

Install

go mod download
go build -o actui ./cmd/actui

Or download the pre-built actui-darwin-arm64 binary from the latest release.

Run

./actui            # normal mode
./actui --dry-run  # preview only, no commands executed

Key Bindings

Context	Key	Action
Anywhere	?	Help screen
Anywhere	q	Quit
Container list	enter	Open container submenu
Container list	s / t	Start / Stop selected container
Container list	d	Delete (type-to-confirm)
Container list	i	Open image management
Container list	M	Open container machine management
Container list	k	Open local Kubernetes cluster management
Container list	m	Daemon management
Container list	r	Refresh
Machine list	enter	Open machine submenu
Machine list	c	Create machine
Machine list	r	Refresh
Machine list	esc	Back to container list
Image list	p	Pull image
Image list	b	Build from Containerfile
Image list	g	Browse registries
Image list	n	Prune unused images
Image list	esc	Back to container list

For full workflow walkthroughs and ASCII screenshots, see docs/user-guide.md.

Configuration

Config is read from (in order):

• ~/.config/actui/config
• ~/Library/Application Support/actui/config

Writes go to ~/Library/Application Support/actui/config.

Example TOML:

default_build_file = "Containerfile"
confirm_destructive_actions = true
theme_mode = "auto"
refresh_on_focus = false
log_retention_days = 7

Logs: ~/Library/Application Support/actui/command.log

Development

Format and lint:

gofmt -w ./...
golangci-lint run ./...

Run tests:

go test ./...

Development Process

This project demonstrates a hybrid AI-assisted workflow:

• Specification: Artifacts (plan, spec, tasks, data model, contracts) authored with Claude Sonnet
• Implementation: Code written by Codex
• Validation: Final testing and oversight by the author

Documentation

Document	Description
docs/user-guide.md	Full workflow walkthroughs, key bindings, troubleshooting
docs/binary-build-automation.md	CI build, SBOM generation, release automation
docs/security-automation.md	OSSF Scorecard, Dependabot, branch protection
docs/ai-menu-map.md	AI agent navigation map and UI ownership guide
docs/speckit-security-hardening-retrospective.md	Retrospective on the security hardening sprint

Security

Repository security is enforced via OSSF Scorecard, Dependabot, and branch protection on main. Releases include SBOM (SPDX 2.3 JSON) and GitHub provenance attestations. See docs/security-automation.md and SECURITY.md for details.

Releases & Binaries

Source builds report actui version dev. Release builds receive the semantic release tag without its v prefix at link time, so actui --version matches the associated GitHub release label after removing v.

Merging to main automatically triggers a build and publishes a versioned GitHub Release with the actui-darwin-arm64 binary and its SBOM. The build uploads the canonical release-version artifact; publishing consumes that same value rather than calculating another tag. See docs/binary-build-automation.md for the full release pipeline.

Contributing

All changes (human or AI-authored) follow the same workflow:

1. Create a branch from main
2. Commit focused changes with clear messages
3. Open a pull request to main
4. Wait for required checks to pass before merge

For AI agent guidelines, see AGENTS.md and docs/ai-menu-map.md.

Direct pushes to main are blocked.

License

MIT — see LICENSE for details.