Quickstart

Run a two-step agent pipeline locally in five minutes. No cluster, no Redis, no API key needed — just Go.

1. Install the ark CLI

Requires Go 1.26 or later.

go install github.com/arkonis-dev/ark-operator/cmd/ark@latest

Verify:

ark --version
# ark v0.9.0 (go1.26)

Alternatively, download a pre-built binary from the releases page:

# macOS (Apple Silicon)
curl -L https://github.com/arkonis-dev/ark-operator/releases/latest/download/ark-darwin-arm64 \
  -o ark && chmod +x ark && sudo mv ark /usr/local/bin/ark

# macOS (Intel)
curl -L https://github.com/arkonis-dev/ark-operator/releases/latest/download/ark-darwin-amd64 \
  -o ark && chmod +x ark && sudo mv ark /usr/local/bin/ark

# Linux (amd64)
curl -L https://github.com/arkonis-dev/ark-operator/releases/latest/download/ark-linux-amd64 \
  -o ark && chmod +x ark && sudo mv ark /usr/local/bin/ark

2. Create a pipeline file

Save this as quickstart.yaml:

apiVersion: arkonis.dev/v1alpha1
kind: ArkTeam
metadata:
  name: quickstart
spec:
  output: ""
  roles:
    - name: research
      model: llama3.2
      systemPrompt: "You are a research assistant. Answer thoroughly."
    - name: summarize
      model: llama3.2
      systemPrompt: "You are a summarizer. Write 3 concise bullet points."
  pipeline:
    - role: research
      inputs:
        prompt: ""
    - role: summarize
      dependsOn: [research]
      inputs:
        content: ""

This defines two agents — research and summarize — wired into a sequential pipeline where the summarizer receives the researcher’s output.

3. Run with mock responses (zero prerequisites) 

ark run quickstart.yaml --provider mock --watch --input topic="transformer architecture"

Expected output:

  research         [running]
  research         [done]    1842 tokens  2.3s
    └─ [mock response for step "research": topic=transformer architecture]
  summarize        [running]
  summarize        [done]    312 tokens  0.8s
    └─ [mock response for step "summarize": content=...]

Flow Succeeded in 3.1s — total: 2154 tokens

The mock provider returns placeholder responses instantly — no API calls, no credentials. Use it to test DAG wiring, dependsOn chains, and template expressions.

4. Run with a real model

Option A: Ollama (local, no API key)

If you have Ollama running:

ollama pull llama3.2

OPENAI_BASE_URL=http://localhost:11434/v1 \
OPENAI_API_KEY=ollama \
  ark run quickstart.yaml --provider openai --watch --input topic="transformer architecture"

Option B: OpenAI 

OPENAI_API_KEY=sk-... \
  ark run quickstart.yaml --provider openai --watch --input topic="transformer architecture"

Option C: Anthropic

Change the model field in quickstart.yaml to claude-sonnet-4-20250514, then:

ANTHROPIC_API_KEY=sk-ant-... \
  ark run quickstart.yaml --watch --input topic="transformer architecture"

Provider auto-detection reads the model name: claude-* routes to Anthropic, gpt-*/o* routes to OpenAI, anything else (like llama3.2) routes to the OpenAI-compatible endpoint at OPENAI_BASE_URL.

What just happened

ark run executed the pipeline entirely in-process — no Kubernetes, no Redis, no operator. The same quickstart.yaml file deploys unchanged to a cluster. The only difference is where it runs.

Next steps

Apache 2.0 · ARKONIS