Quick Start

Goal: open ColimaStack, start a Colima profile, run a sample container, and verify it appears in the app.

Prerequisites

• macOS 14 or later. See Compatibility for the current support matrix.
• Colima and the Docker CLI for Docker inventory.
• kubectl only for the optional Kubernetes check.
• A local build of ColimaStack. Public notarized downloads are not documented as available yet; see Install for the current acquisition path.

Step 1: Install or open ColimaStack

Existing Colima user:

1. Build or open ColimaStack from source.
2. Let the app run its startup checks.
3. Select an existing profile in the sidebar.

New Colima setup:

1. Install Colima and Docker CLI.
2. Build or open ColimaStack from source.
3. Use Create Profile in the Profiles sidebar if you do not already have a profile, or start default from Terminal with colima start.

Full install and build steps are in Install.

Step 2: Confirm prerequisites

Run the smallest useful checks:

colima version
docker version

For Kubernetes workflows:

kubectl version --client

If a command is missing, open Diagnostics or return to Install.

Step 3: Start or select a profile

In ColimaStack:

1. Open Profiles.
2. Select an existing profile, or choose Create Profile.
3. Use Start from the toolbar or menu bar if the selected profile is stopped.

Success looks like:

• The selected profile shows Running.
• Overview shows a Docker context and socket for Docker profiles.
• Containers no longer shows Docker endpoint unavailable.

Profile behavior and destructive actions are documented in Profiles.

Step 4: Run a visible sample container

ColimaStack reads Docker inventory from the selected profile’s Docker context. If your selected profile is the default Colima profile, run:

docker run -d --name colimastack-quickstart -p 8080:80 nginx:alpine

For a named profile, either switch Docker to that context or pass the context explicitly:

docker context use colima-<profile>
# or
docker --context colima-<profile> run -d --name colimastack-quickstart -p 8080:80 nginx:alpine

Then open Containers in ColimaStack and click Refresh. The container should appear with image nginx:alpine, state running, and a published port similar to 0.0.0.0:8080->80/tcp.

Cleanup:

docker rm -f colimastack-quickstart

See Docker Containers for empty states and command details.

Step 5: Optional Kubernetes verification

Kubernetes must be enabled on the selected Colima profile. In ColimaStack, open Cluster; if Kubernetes is disabled, use Enable Kubernetes.

Minimal terminal check:

kubectl config current-context
kubectl get nodes

Then open Cluster, Workloads, or Services in ColimaStack and click Refresh. Workload metrics appear only when kubectl top works for the cluster.

See Kubernetes for supported resources and failure cases.

Step 6: Troubleshooting links

• Diagnostics for missing tools, stopped profiles, Docker context errors, and Kubernetes context errors.
• Install for source builds and dependency setup.
• Profiles for lifecycle actions.
• Docker Containers for container inventory.
• Kubernetes for cluster checks.
• Command API for exact command shapes.