Skip to main content

​
Quick Start Guide

This guide will walk you through getting started with Container Kit, from installation to managing your first container. You’ll learn the basics of the interface and essential container operations.
This guide assumes you have already installed Container Kit. If not, see the Installation Guide first.

​
Launch Container Kit

Start Container Kit using one of these methods: 
# From Spotlight
# Press Cmd + Space, type "Container Kit", and press Enter

# From Terminal
open -a "Container Kit"

# From Applications folder
# Navigate to Applications → Container Kit

​
Understanding the Interface

Container Kit features a modern, intuitive interface designed following Apple’s Human Interface Guidelines:

​
Main Dashboard

The dashboard provides an overview of your container ecosystem:
  • Container List - All your containers with status indicators
  • Resource Usage - CPU, memory, and storage metrics with LayerChart visualizations
  • Quick Actions - Start, stop, restart, and delete containers
  • Search & Filter - Find containers by name, status, or type
  • Containers - View and manage all containers
  • Terminal - Integrated terminal for advanced container commands
  • Settings - Configure Container Kit preferences and themes

​
Theme Options

Container Kit supports multiple themes that automatically sync with your system:
  • Light Mode - Clean, bright interface for daytime use
  • Dark Mode - Easy on the eyes for night work
  • System - Automatically matches your macOS appearance settings
Switch themes in Settings → Appearance → Theme

​
Managing Your First Container

Let’s walk through the essential container operations using Container Kit.

​
Viewing Containers

1

Open the Containers view

Click on Containers in the sidebar to see all containers on your system.The container list shows:
  • Container name and ID
  • Current status (Running, Stopped, Paused)
  • Resource usage (CPU, Memory)
  • Last modified timestamp
2

Filter containers by type

Use the filter dropdown to view specific container types:
  • App Sandbox Containers - Sandboxed macOS applications
  • System Containers - System services and processes
  • Virtualization Containers - Apple virtualization environments
3

Search for a container

Use the search bar at the top to find containers by:
  • Container name
  • Container ID
  • Application bundle ID
# Example search queries:
com.apple.Safari
container-abc123
MyApp

​
Container Operations

1

View container details

Click on any container to view detailed information:
  • Overview - Status, ID, creation date
  • Resources - CPU, memory, disk usage with real-time charts
  • Networking - Network configuration and DNS settings
  • Registry - Container registry and policy information
Container Kit uses the Apple Container CLI under the hood for all operations, ensuring native compatibility and performance.
2

Start a container

To start a stopped container:
  1. Select the container from the list
  2. Click the Start button in the action bar
  3. Wait for the status to change to “Running”
You can also start containers from the terminal:
# Container Kit uses the bundled Apple Container CLI
# Access it through the integrated terminal
container start <container-id>
3

Stop a container

To stop a running container:
  1. Select the container from the list
  2. Click the Stop button in the action bar
  3. Confirm the action if prompted
Stopping a container will terminate all running processes inside it. Ensure you’ve saved any work before stopping.
4

Delete a container

To permanently remove a container:
  1. Select the container from the list
  2. Click the Delete button (trash icon)
  3. Confirm the deletion in the dialog
Deleting a container is permanent and will remove all associated data. This action cannot be undone.

​
Using the Integrated Terminal

Container Kit includes a powerful terminal integration using xterm for advanced container operations.
1

Open the terminal

Click Terminal in the sidebar to open the integrated terminal.The terminal provides:
  • Full bash shell access
  • Access to the bundled Apple Container CLI
  • Syntax highlighting and autocomplete
  • Multiple terminal tabs
2

Run container commands

Use the Apple Container CLI directly:
# List all containers
container list

# Get container info
container info <container-id>

# View container logs
container logs <container-id>

# Inspect container configuration
container inspect <container-id>
3

Manage container networking

Configure container networking settings:
# View network configuration
container network list

# Configure DNS for a container
container network dns <container-id> --add 8.8.8.8

# View network interfaces
container network inspect <container-id>

​
Container Monitoring

Container Kit provides real-time monitoring and visualization of container resources.

​
Resource Metrics

The dashboard displays live metrics using LayerChart:
  • CPU Usage - Per-container CPU utilization with historical trends
  • Memory Usage - RAM consumption and allocation
  • Disk I/O - Read/write operations and throughput
  • Network Traffic - Inbound and outbound data transfer

​
Setting Alerts

Alert functionality is under active development. Resource thresholds and notifications will be available in a future release.

​
Database and Storage

Container Kit uses LibSQL (SQLite-compatible) for local data storage and Drizzle ORM for type-safe database operations.

​
Data Persistence

Container Kit stores:
  • Container metadata and status
  • User preferences and settings
  • Historical resource usage data
  • Terminal history and favorites
Database location: ~/Library/Application Support/com.ethercorps.container-kit/container-kit.db

​
Database Migrations

Container Kit automatically applies database migrations on startup. If you’re building from source: 
# Generate new migrations from schema changes
pnpm db:generate

# This will:
# 1. Run drizzle-kit generate to create SQL migrations
# 2. Run generate-migrations.ts to create Rust bindings
# 3. Update migration files in src-tauri/migrations/

​
Configuration and Settings

Customize Container Kit to match your workflow.
1

Open Settings

Click the gear icon in the sidebar or press Cmd + , to open Settings.
2

Configure appearance

Navigate to Appearance to customize:
  • Theme - Light, Dark, or System
  • Accent Color - Choose your preferred accent color
  • Animations - Enable/disable Motion-powered animations
  • Font Size - Adjust terminal and UI font sizes
3

Set container defaults

Navigate to Containers to configure:
  • Default Storage Location - Where container data is stored
  • Auto-start Containers - Containers to start on app launch
  • Resource Limits - Default CPU and memory limits
4

Configure terminal

Navigate to Terminal to customize:
  • Shell - Default shell (bash, zsh, etc.)
  • Color Scheme - Terminal color themes
  • Font - Monospace font for terminal
  • Scrollback - Terminal history buffer size

​
Keyboard Shortcuts

Boost your productivity with keyboard shortcuts:
ActionShortcut
Open SettingsCmd + ,
New Terminal TabCmd + T
Close TabCmd + W
Search ContainersCmd + F
Refresh Container ListCmd + R
Toggle SidebarCmd + B

​
Development Mode

If you’re developing with Container Kit, you can run it in development mode with hot reload: 
cd ContainerKit
pnpm tauri dev
This will:
  • Start the Vite dev server on http://localhost:1420
  • Launch the Tauri app with hot module replacement
  • Enable debug logging and development tools
  • Watch for file changes and automatically rebuild
Development mode requires the full source code. See the Installation Guide for setup instructions.

​
Troubleshooting

​
Common Issues

If containers aren’t appearing in the list:
  1. Refresh the list - Press Cmd + R or click the refresh button
  2. Check permissions - Ensure Container Kit has Full Disk Access in System Settings
  3. Restart the app - Quit and relaunch Container Kit
  4. Check terminal - Run container list in the integrated terminal to verify the CLI is working
If the integrated terminal isn’t responding:
  1. Check shell path - Verify your shell is correctly configured in Settings
  2. Restart terminal - Close and reopen the Terminal tab
  3. Check permissions - Ensure Automation permissions are granted
  4. View logs - Check Console.app for Container Kit errors
If Container Kit is consuming too many resources:
  1. Close unused terminals - Each terminal tab uses resources
  2. Reduce refresh rate - Adjust polling interval in Settings
  3. Disable animations - Turn off Motion animations in Settings
  4. Restart the app - Quit and relaunch to clear memory
If you see database migration errors:
  1. Backup your data - Copy ~/Library/Application Support/com.ethercorps.container-kit/
  2. Reset database - Delete container-kit.db and restart (data will be lost)
  3. Check migrations - Ensure all migrations in src-tauri/migrations/ are present
  4. Report issue - Create an issue on GitHub with error logs

​
Next Steps

Now that you’re familiar with the basics, explore more advanced features:

Contributing Guide

Learn how to contribute to Container Kit development

GitHub Repository

View source code, report issues, and join discussions

Apple Container CLI

Learn more about Apple’s official container CLI

Report Issues

Found a bug? Let us know on GitHub Issues

​
Getting Help

If you need assistance:
Container Kit is under heavy development. Features and APIs may change between releases. Check the repository regularly for updates.

Build docs developers (and LLMs) love

Get started for freeTalk to us