Ark Setup

This skill helps you set up and install the Ark platform from source using the ark-cli.

When to use this skill

Use this skill when:

User wants to install or set up Ark
User needs to deploy Ark to their local cluster
User asks about getting Ark running
User needs to troubleshoot Ark installation issues

Prerequisites

Docker-in-Docker (DinD) - Required for Kind to create clusters inside this container
kubectl - Kubernetes CLI
Helm - For installing Ark components
Node.js - For building the ark-cli tool

Step 0: Verify Docker-in-Docker is available

CRITICAL: You MUST verify Docker is accessible before attempting to create a Kind cluster.

docker info

If this command fails, STOP IMMEDIATELY. Do not attempt to create a Kind cluster. Report to the user:

"Cannot proceed: Docker is not available. Kind requires Docker-in-Docker (DinD) to create clusters inside this container. The container must be started with the ark profile (devspace dev -p ark) which adds the DinD sidecar."

If Docker is available, proceed to the next step.

Step 1: Clone the Ark repository

First, ensure you have cloned the Ark repository. If the user provided an org/repo, use that. Otherwise, use the default:

git clone git@github.com:mckinsey/agents-at-scale-ark.git
cd agents-at-scale-ark

If working on a pull request, checkout the PR branch:

git fetch origin pull/<PR_NUMBER>/head:pr-<PR_NUMBER>
git checkout pr-<PR_NUMBER>

Step 2: Set up Kubernetes cluster

Step 2a: Clean up existing clusters

CRITICAL: Always delete existing Kind clusters first to avoid conflicts and resource exhaustion.

# Delete any existing ark-cluster
kind delete cluster --name ark-cluster 2>/dev/null || true

# Verify no ark-cluster exists
kind get clusters

Step 2b: Create cluster and configure kubeconfig

# Create Kind cluster
kind create cluster --name ark-cluster

# REQUIRED: Get the control plane container's IP address
CONTROL_PLANE_IP=$(docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' ark-cluster-control-plane)

# Export kubeconfig and replace hostname with IP
mkdir -p ~/.kube
kind get kubeconfig --name ark-cluster --internal | sed "s/ark-cluster-control-plane/$CONTROL_PLANE_IP/g" > ~/.kube/config

# Verify connection works
kubectl cluster-info

Why IP address is required: This agent runs inside Docker. The default 127.0.0.1 doesn't work across containers, and the --internal hostname may not be resolvable. Using the actual container IP ensures connectivity.

Step 3: Build the ark-cli from source

Build the CLI from the cloned repository. This ensures you use the version matching the code being tested:

cd agents-at-scale-ark
npm install
cd tools/ark-cli
npm install
npm run build

Step 4: Install Ark using ark-cli

Use the built CLI to install Ark. Use direct node execution for reliability:

# From the tools/ark-cli directory
node dist/index.js install --yes --wait-for-ready 5m

Or if you're in the repo root:

node tools/ark-cli/dist/index.js install --yes --wait-for-ready 5m

The --yes flag auto-confirms prompts, and --wait-for-ready waits for services to be ready.

Step 5: Verify installation

Check installation status:

node tools/ark-cli/dist/index.js status

Or use kubectl:

kubectl get pods -n ark
kubectl get pods -n ark-system
kubectl get services -n ark

Wait until all pods show as Running and services are ready.

Troubleshooting

Docker not available / Kind fails to create cluster

If docker info fails or kind create cluster fails with Docker errors:

STOP. This container does not have Docker-in-Docker (DinD) configured. Report to the user:

"Cannot create Kind cluster: Docker is not available. The container must be started with the ark profile (devspace dev -p ark)."

Check pod status

kubectl get pods -A -o wide | grep -E '(ark|cert-manager)'
kubectl describe pod -n ark <pod-name>

View logs

kubectl logs -n ark deployment/ark-api
kubectl logs -n ark-system deployment/ark-controller

Kubeconfig issues with Kind

If kubectl/helm can't reach the cluster API server (connection refused or hostname not found):

# Get the control plane IP and reconfigure kubeconfig
CONTROL_PLANE_IP=$(docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' ark-cluster-control-plane)
kind get kubeconfig --name ark-cluster --internal | sed "s/ark-cluster-control-plane/$CONTROL_PLANE_IP/g" > ~/.kube/config

# Verify the server address is an IP, not 127.0.0.1 or a hostname
kubectl config view --minify | grep server
# Should show: server: https://172.x.x.x:6443

Working with Ark

Once Ark is running:

kubectl apply -f samples/agents/my-agent.yaml

kubectl get agents
kubectl get queries
kubectl get teams

kubectl describe agent <agent-name>

Phoenix Telemetry

Install Phoenix for OpenTelemetry tracing:

node tools/ark-cli/dist/index.js install marketplace/services/phoenix

Access dashboard:

kubectl port-forward -n phoenix svc/phoenix-svc 6006:6006
# Open http://localhost:6006

Important

DO NOT use scripts/quickstart.sh - it is deprecated. Always use ark-cli as described above.

DO NOT use npm install -g @agents-at-scale/ark - always build ark-cli from source to match the PR code being tested.