Run Your First Container

This first workflow uses the source-backed container start --name ... --image form, which defines and starts a container in one step. That dual behavior is a MacTain convention: mactain container start <name> starts something that already exists, while mactain container start --name ... --image ... creates a new definition and starts it immediately.

Prerequisites

MacTain is installed.
The CLI is available in Terminal.
The Engine and runtime assets have been verified.
You can reach the registry that hosts the image you want to run.

Start A Container

Use a fully qualified image reference when possible.

mactain container start \
  --name hello-web \
  --image docker.io/library/nginx:latest \
  --detach

List containers after starting:

mactain container list

Inspect the container when you need details:

mactain container inspect hello-web

The command above uses MacTain's defaults: 2 CPUs, 2048 MiB of memory, the mactain-default network, no autostart, no Docker API shim access, and no persistent log retention. Those defaults are a good first-run choice for a small stateless service. Add explicit flags once you know the workload needs different resources, startup behavior, networking, storage, or logging.

Command Reference

Command	Description	Why it appears in this guide
`mactain container start --name ... --image ...`	Defines and starts a new container in one command.	Fastest path for a first standalone container.
`mactain container start <name>`	Starts an existing container definition.	Reuses a container that was already created.
`mactain container list`	Lists defined and running containers.	Confirms MacTain created the container.
`mactain container inspect <name>`	Shows the persisted container definition.	Shows defaults and explicit settings.
`mactain container stats <name>`	Shows runtime telemetry.	Helps decide whether default resources are enough.
`mactain container logs <name>`	Fetches container logs.	First diagnostic check after startup.
`mactain container status <name>`	Shows detailed runtime status.	Confirms health and runtime details.
`mactain container stop <name>`	Stops the container.	Required before replacing the example definition.
`mactain container remove <name>`	Removes the container definition.	Required when changing immutable define-time options.

Defaults And Behavior

The first hello-web example uses default resources: 2 CPUs and 2048 MiB.
The default network is mactain-default.
The example does not publish a port until the practical use cases introduce --publish.
The example does not use persistent storage. Add volumes before storing data you need to keep.
Use bind mounts for files you edit on your Mac, named volumes for durable app data, and tmpfs for temporary scratch paths.
Define-time options are immutable. Stop and remove the example container before recreating it with different resources, mounts, ports, DNS, or health settings.
MacTain does not have a separate run subcommand. Use container start --name ... --image ... for Docker run-style create-and-run workflows.
Add --remove when a create-and-start container should be removed after it stops.

View Logs

mactain container logs hello-web

Use command help for optional log flags such as follow mode, line count, boot logs, or log source selection.

Practical Use Cases

Use case: confirm the container command shape before running it

Use this when you are unsure which flags your installed release supports.

mactain container start --help
mactain container create --help

Read the usage forms first. Use container start --name ... --image ... when you want to define and start in one command. Use container create when you want to define the container first and start it later.

Use case: understand MacTain's two start modes

Use this when you are deciding whether you are starting something that already exists or creating a new container and starting it immediately.

mactain container start hello-web
mactain container start \
  --name hello-web \
  --image docker.io/library/nginx:latest \
  --detach

The first command starts the existing hello-web definition. The second command creates a new hello-web definition and starts it. If hello-web already exists, remove and recreate it to change define-time options.

Use case: inspect the defaults MacTain applied

Use this immediately after your first successful start so you know what MacTain created.

mactain container inspect hello-web
mactain container stats hello-web

Look for the resource allocation in inspect output and live usage in stats output. If the container is consistently near its memory allocation or CPU allocation, recreate it with explicit --memory-mib or --cpus values.

Use case: run a one-time container that is removed after exit

Use this for a command that should run once and leave no container definition behind. This is the closest MacTain shape to a one-off Docker run --rm command.

mactain container start \
  --name hello-once \
  --image docker.io/library/alpine:latest \
  --command /bin/sh \
  --args -lc \
  --args "echo hello from MacTain" \
  --remove

MacTain creates the container, runs the foreground command, and removes the container after it exits.

Use case: bind mount a local folder

Use this when the container should read files from your Mac, such as local source, docs, or config. This example mounts ./docs from the current Terminal directory into /workspace/docs inside the container.

mactain container start \
  --name docs-reader \
  --image docker.io/library/alpine:latest \
  --mount type=bind,source=./docs,target=/workspace/docs,readonly \
  --command /bin/sh \
  --args -lc \
  --args "ls -la /workspace/docs" \
  --remove

Use readonly when the container should not write back to the host folder.

Use case: keep data in a named volume

Use this when data should survive container replacement.

mactain volume create hello-data
mactain container start \
  --name hello-data-demo \
  --image docker.io/library/alpine:latest \
  --mount type=volume,source=hello-data,target=/data \
  --command /bin/sh \
  --args -lc \
  --args "date > /data/last-run.txt" \
  --remove
mactain volume fs list hello-data /

Use Volumes for backup, restore, and file inspection commands.

Use case: run a temporary test service

Use this when you want a service container that can be removed after it stops.

mactain container start \
  --name hello-temp \
  --image docker.io/library/nginx:latest \
  --publish 8080:80 \
  --detach \
  --remove
mactain container logs hello-temp --lines 50

Do not use --remove for containers that own data you still need. Put durable data in Volumes.

Use case: recreate with explicit resources

Use this after the first run when the default 2 CPUs and 2048 MiB do not match the workload. Since container definitions are immutable, remove or replace the old definition, then create a new one with explicit resources.

mactain container stop hello-web
mactain container remove hello-web
mactain container start \
  --name hello-web \
  --image docker.io/library/nginx:latest \
  --cpus 1 \
  --memory-mib 1024 \
  --detach

Use smaller values for light test services. Use larger values for databases, build tools, application servers, or containers that terminate under memory pressure.

Use case: run a service with a basic health check

Use this when you want MacTain to check whether a container is reachable after start.

mactain container start \
  --name web-health \
  --image docker.io/library/nginx:latest \
  --publish 8081:80 \
  --health-type tcp \
  --health-port 80 \
  --detach
mactain container status web-health

Health checks default to 3 retries. For a slow-starting service, add a start period before judging health failures:

mactain container start \
  --name slow-api \
  --image ghcr.io/acme/slow-api:latest \
  --publish 8082:8080 \
  --health-type http \
  --health-url http://127.0.0.1:8080/health \
  --health-start-period 45s \
  --health-retries 5 \
  --detach

Troubleshooting Entry Points

Runtime missing: return to Verify installation.
Image pull failure: check registry access and Troubleshooting.
App not reachable: review Networking.
Need persistent data: review Volumes.

Next Steps

After one container works, review Images so you understand image pulling and local image inventory, then continue to Blueprints to capture a repeatable app definition.