How to Start a Stopped Container Interactively: Command Guide and Architecture

Use container start -i -a <container-name> to start a stopped container interactively, reopening stdin and attaching stdout/stderr to your terminal for full bidirectional communication.

Apple Container is Apple's open-source container runtime designed for macOS, enabling Linux-compatible container workflows on Apple silicon. When you need to restart a stopped container and interact with its primary process, the container start command with specific flags orchestrates a multi-component workflow to restore the container state and attach your terminal. Understanding how to start a stopped container interactively requires knowledge of both the CLI syntax and the underlying XPC-based architecture.

Understanding the Interactive Flags

The --interactive and --attach flags control how your terminal connects to the container process.

--interactive (or -i) keeps the container's standard input (stdin) open, allowing you to send commands directly to the running process. Without this flag, the container runs with no input source attached.

--attach (or -a) connects your terminal to the container's standard output (stdout) and standard error (stderr), displaying the process output in your shell. Combined with --interactive, this creates a fully interactive terminal session.

Step-by-Step Internal Workflow

When you execute container start with interactive flags, the request traverses multiple system components before your container resumes execution.

CLI Parsing and XPC Request Construction

In Sources/CLI/Commands/StartCommand.swift, the Swift CLI implementation parses your command-line arguments and constructs an XPC request containing the container ID and the requested flags (interactive and attach). This request encapsulates everything needed to identify which container to start and how to configure its I/O streams.

Runtime Service and VM Boot

The XPC request reaches the container-apiserver, a launch-agent that runs persistently on macOS. The RuntimeService.swift file in Sources/Services/RuntimeLinux/Server/RuntimeService.swift implements the logic that boots the lightweight Linux VM backing the container if it is not already running. The source code explicitly states it will "Start the VM and the guest agent process for a container," ensuring the runtime environment exists before attempting to launch the container workload.

Container Process Creation

Once the VM is ready, ContainersService.swift in Sources/Services/ContainerAPIService/Server/Containers/ContainersService.swift handles the actual container startup. This service creates the process inside the running container, applying the interactive flag to keep stdin open and the attach flag to configure stream redirection. The startup path receives these boolean values from the XPC request and configures the container's init process accordingly.

Terminal Attachment

If you specified --attach, the CLI opens pipes to the container's stdout and stderr, forwarding data to your terminal in real-time. This completes the interactive session setup, allowing bidirectional communication between your shell and the container process.

Practical Usage Examples

The following commands demonstrate how to start a stopped container interactively using the Apple Container CLI:

# Keep stdin open for interactive input (no output attachment)

container start -i mycontainer

# Full interactive console with stdin, stdout, and stderr attached

container start -i -a mycontainer

# Long-form flags for readability in scripts

container start --interactive --attach mycontainer

If the container's primary process is not a shell, you can start it interactively and then execute a shell in a separate step:

# Start the container and attach to its current process, then exec a shell

container start -i -a mycontainer && container exec -i -t mycontainer /bin/bash

Summary

• Use container start -i -a to restart a stopped container with full interactive terminal access according to the Apple Container source code.
• The --interactive (-i) flag keeps stdin open, while the --attach (-a) flag connects stdout and stderr to your terminal.
• Source files StartCommand.swift, ContainersService.swift, and RuntimeService.swift handle the CLI parsing, XPC communication, VM boot, and process creation chain.
• The architecture involves the CLI sending XPC requests to the container-apiserver, which coordinates with the runtime service to boot the Linux VM and launch the container process.

Frequently Asked Questions

What is the difference between the --interactive and --attach flags when starting a container?

The --interactive (or -i) flag keeps the container's standard input open, allowing you to type commands into the running process. The --attach (or -a) flag connects your terminal to the container's output streams (stdout and stderr). For a fully interactive session where you can both send input and see output, you need both flags.

Can I start a stopped container interactively without attaching to it?

Yes, you can use container start -i <container-name> to keep stdin open without attaching stdout and stderr. This is useful when you want to send input to the container but do not need to see its output in your current terminal, though this is less common for interactive debugging.

How do I access a shell after starting a container interactively?

If the container's primary process is not a shell, start the container with container start -i -a <container-name> and then use container exec -i -t <container-name> /bin/bash in a subsequent command. The start command launches the container's defined entrypoint, while exec runs additional commands in the already-running container.

Where does the Apple Container runtime handle the start command logic?

The start command is parsed in Sources/CLI/Commands/StartCommand.swift, which builds an XPC request to the container-apiserver. The server-side logic resides in Sources/Services/ContainerAPIService/Server/Containers/ContainersService.swift, which forwards to Sources/Services/RuntimeLinux/Server/RuntimeService.swift for VM management and process execution.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}