Warning

Major Refactor in Progress

A large foundation refactor is currently under review in PR #48. This introduces significant changes across the codebase and will likely require existing branches to be rebased with manual conflict resolution.

If you’re planning to contribute, it’s recommended that you base new work on this branch until it has been merged.

Contained

A native macOS control surface for Apple's container CLI.

_{Pre-1.0 and actively polishing.}

What It Does

Contained gives containers, images, volumes, networks, registries, logs, templates, app-managed health, and restart behavior a Mac-first SwiftUI interface while keeping the underlying command line visible.

• Run, edit, stop, restart, inspect, and delete containers.
• Browse Liquid Glass cards with local-only tint, icon, nickname, and graph personalization.
• Manage images, tags, updates, archives, volumes, networks, registry credentials, templates, activity history, and system resources.
• Import Compose files into editable run forms instead of launching opaque stacks.
• Preview the exact container command before privileged run/edit operations.
• Try experimental toolbar panels, morph surfaces, command palette, Docker Hub search, image build workspace, keyboard shortcuts, and Compose import from Settings.

Install

Download the latest .dmg from Releases.

Sparkle updates are built in. During pre-1.0 development, fresh installs default to the Nightly channel so they can receive current builds. Stable, Beta, and Nightly can be changed in Settings -> Updates.

Requirements:

• macOS 26 or later on Apple silicon
• Apple's container CLI 1.0.0 on PATH
• Xcode 26 / Swift 6.2+ for local development

Build

Contained has two supported development entry points over the same package graph.

Path	Use it for
Contained.xcworkspace	Native Xcode build/run, SwiftUI previews, and manual UI iteration
Package.swift	CI, tests, bundle generation, signing, notarization, release notes, and appcasts

open Contained.xcworkspace
swift build
swift test
xcodebuild -workspace Contained.xcworkspace -scheme Contained -configuration Debug build
xcodebuild -workspace Contained.xcworkspace -scheme Contained -configuration Debug test
./Scripts/package.sh app debug
open Contained.app

Maintainers use Scripts/package.sh notarized and Scripts/appcast.sh generate for signing, notarization, DMG creation, GitHub release notes, and Sparkle appcasts.

Documentation

Start with the documentation index. The most-used pages are:

• App: Home, Installation, Keyboard Shortcuts, Troubleshooting, Updates, System Settings
• Features: Feature Overview, Containers, Images, Resources, Creation Workflow, Run / Edit Form, Compose Import, Command Palette
• Architecture: Architecture, Runtime Adapters, Design System
• Development: Contributing, Issues and Discussions, Documentation Map, Localization
• Release: Release Runbook

Package docs live beside each local package:

• ContainedCore
• ContainedUI
• ContainedUX

The checked-in wiki map explains how maintained docs map to the separate GitHub wiki repository.

Architecture

The root package contains a tiny SwiftPM launcher and the shared app implementation, then consumes standalone local packages.

Owner	Responsibility
ContainedCore	Backend orchestration through Core.*: runtime descriptors, canonical container models, command previews, Compose import/export, Apple container adapter internals, metrics, typed errors, and migration planning
ContainedUI	Visual system through UI.*: tokens, materials, cards, panels, controls, state views, and charts
ContainedUX	Interaction infrastructure through UX.*: safe areas, morphing, source measurement, and panel placement
ContainedApp	SwiftUI shell, navigation, feature views, stores, history, settings, Sparkle, presentation mapping, localization, and app policy
Contained	SwiftPM executable launcher used by command-line builds and bundle scripts

Integration is CLI-based rather than private-framework based. The app talks to Core.Orchestrator; Core owns adapter-specific argv and process details. Personalization and app-managed metadata stay local to Contained so the user's container resources remain clean when used directly from the terminal.

Core also exposes a separate ContainedCoreFixtures product for deterministic test/preview data under Core.Fixtures.*. Normal app and distributable bundle targets do not link it.

Contributing And Support

Read the contributing guide before opening a larger PR.

• Use Discussions Q&A for setup help and questions.
• Use issues for actionable bugs, crashes, regressions, and tracked feature work.
• Use private vulnerability reporting for security issues.

License

Contained is source-available and free for non-commercial use under the PolyForm Noncommercial License 1.0.0. The Contained name and branding are reserved; see NOTICE.