Apple Container — VS Code / Cursor Extension

Manage Apple's native container CLI directly from VS Code or Cursor. Browse and control containers, images, volumes, and networks from a dedicated sidebar; stream logs, open shells, monitor live stats, watch disk usage, and build OCI images from Dockerfiles — all without leaving your editor.

Requirements

Installation

Development / from source

git clone https://github.com/your-org/apple-container-vscode
cd apple-container-vscode
npm install
npm run compile

Press F5 in VS Code / Cursor to open an Extension Development Host with the extension loaded.

Package as VSIX

npm install -g @vscode/vsce
vsce package
# → apple-container-0.x.x.vsix

Install via Extensions: Install from VSIX… in the command palette.

Configuration

// .vscode/settings.json
{
  "appleContainer.cliPath": "/usr/local/bin/container",
  "appleContainer.refreshInterval": 5
}

Features

Containers view

Lists all containers (running and stopped) with image name, state, and IP address.

Expandable items — each container with published ports or mounts can be expanded to show:

• Port sub-items — displays hostPort → containerPort/protocol. Click a TCP port item to open it in the browser instantly.
• Mount sub-items — shows the bind/volume mount destination, source path, and read/write mode.

Hover tooltip — hovering a container shows a rich tooltip with:

• Image, state, and network address
• Full port-forwarding table with clickable "Open in browser" links for running containers
• Bound mounts with source paths

Context menu actions:

Title bar buttons:

Images view

Lists all local OCI images with architecture, size, and creation date.

Context menu actions:

Title bar buttons:

Volumes view

Lists all volumes with driver, format, and actual disk usage (reads the source path with du -sk — not the quota).

Context menu: Inspect, Delete (with confirmation).

Title bar: Create Volume, Refresh, Prune Unused Volumes.

Networks view

Lists all container networks with driver, gateway, and subnet.

Context menu: Inspect, Delete (with confirmation).

Title bar: Create Network, Refresh, Prune Unused Networks.

System status bar

The bottom status bar item shows the current system service state (● running / ○ stopped).

• Click to toggle: starts the service if stopped, stops it if running.
• Polls the service every N seconds automatically.

Live Stats dashboard

Open via the $(pulse) button or Apple Container: Show Live Stats in the command palette.

Displays a card for each running container with:

• CPU — percentage bar + sparkline chart of the last 30 samples
• MEM — usage/limit bar + sparkline chart
• NET RX / TX — cumulative network I/O bytes
• BLK READ / WRITE — cumulative block device I/O bytes

Rate mode toggle — click "Show rates /s" in the panel header to switch all I/O values from cumulative totals to live bytes-per-second throughput rates computed from consecutive sample deltas.

Stats refresh every 3 seconds automatically.

Disk Usage panel

Open via Apple Container: Disk Usage (system df) or the $(pie-chart) button.

Runs container system df and displays a table of disk usage for Images, Containers, and Volumes (total count, active count, size, reclaimable space). Each row with reclaimable space shows a Reclaim button that prunes the corresponding resource type.

Dockerfile CodeLens

When a Dockerfile or Containerfile is open in the editor, two CodeLens actions appear above every FROM instruction:

• Build image — triggers the build wizard for that Dockerfile
• Build & Run — builds the image and immediately launches the run wizard

Build & Run wizard

Triggered from the command palette, title bar, or CodeLens.

• Build — prompts for Dockerfile path, context directory, and image tag. Streams docker build output to the Apple Container output channel.
• Run — interactive form to set the container name, port mappings (-p), environment variables (-e), volume mounts (-v), and extra CLI flags.

Registry

Available from the Images title bar or command palette:

File copy

Copy files between the host and a running container:

Crash notifications

A background watcher (polls every 8 s) tracks running containers. When a previously-running container disappears, a VS Code notification appears:

Container "my-app" stopped unexpectedly. [Restart] [Dismiss]

Clicking Restart runs container start <id> immediately.

Auto-refresh (smart polling)

All four sidebar views refresh automatically at the configured interval (appleContainer.refreshInterval).

The refresh is change-aware: on each tick, the extension fetches a lightweight snapshot of each resource list and compares it with the previous snapshot. The tree only re-renders if the data actually changed — no unnecessary UI redraws or flicker when nothing is happening.

Command palette reference

All commands are under the Apple Container category (Cmd+Shift+P):

Right-click any item in the sidebar for additional context-menu actions.

Architecture

VS Code / Cursor
│
├── Activity Bar — Apple Container sidebar
│   ├── Containers view    src/containersProvider.ts
│   ├── Images view        src/imagesProvider.ts
│   ├── Volumes view       src/volumesProvider.ts
│   └── Networks view      src/networksProvider.ts
│
├── Status bar item        src/statusBar.ts
├── Live Stats webview     src/statsWebview.ts
├── Disk Usage webview     src/systemDf.ts
├── Dockerfile CodeLens    src/dockerfileCodeLens.ts
│
├── Background services
│   ├── AutoRefresher      src/autoRefresh.ts   (change-aware polling)
│   └── CrashWatcher       src/crashWatcher.ts  (stop detection + notifications)
│
├── Commands               src/commands.ts
├── Registry commands      src/registryCommands.ts
├── Build & Run            src/buildRun.ts
├── File copy              src/fileCopy.ts
├── Output channel         src/output.ts
└── CLI wrapper            src/cli.ts
        │
        ▼  child_process.execFile / spawn
        │
   container ls / start / stop / rm / exec / logs
   container image ls / pull / push / tag / build / rm
   container volume ls / create / rm / prune
   container network ls / create / rm / prune
   container system status / start / stop / df
   container stats / copy / registry login

Limitations

• Requires Apple Silicon + macOS 26 Tahoe. Intel Macs are not supported by the container CLI.
• The extension does not install or upgrade the container CLI — manage that separately via the releases page.
• Registry login stores credentials in the CLI's credential store, not VS Code's secret storage.

License

MIT