contained-app

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.

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.

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.