README
¶
ark
Ship AI teams like you ship services. ark brings AI agents into Kubernetes as first-class resources - define your team, deploy it, operate it with every tool you already know.
Status: alpha. Core primitives are stable. Not recommended for production workloads yet.
Full documentation at docs.arkonis.dev.
Prerequisites
- Kubernetes 1.33+
- Helm 3.12+
- kubectl
Quick start
# 1. Add the Helm repo
helm repo add arkonis https://charts.arkonis.dev
helm repo update
# 2. Install the operator
helm install ark arkonis/ark \
--namespace ark-system --create-namespace
# 3. Create a Secret with your LLM API key in your team's namespace
kubectl create secret generic my-llm-keys \
--namespace default \
--from-literal=ANTHROPIC_API_KEY=sk-ant-...
# 4. Apply a sample team (references the secret directly in the CR)
kubectl apply -f https://raw.githubusercontent.com/arkonis-dev/ark-cookbook/main/teams/01-simple-pipeline/blog-writer.yaml
# 5. Trigger a run
ark trigger blog-writer-team -n default \
--input '{"topic": "Kubernetes operators explained"}'
# 6. Watch it run
ark status -n default
Install the ark CLI for local development: see ark-cli.
Contributing
Issues, ideas, and PRs are welcome. See CONTRIBUTING.md for architecture notes and design decisions before diving in.
Code of Conduct
This project follows the Contributor Covenant Code of Conduct.
License
Apache 2.0 - see LICENSE
Directories
¶
| Path | Synopsis |
|---|---|
|
api
|
|
|
v1alpha1
Package v1alpha1 contains API Schema definitions for the arkonis v1alpha1 API group.
|
Package v1alpha1 contains API Schema definitions for the arkonis v1alpha1 API group. |
|
internal
|
|
|
agent/budget
Package budget provides agent-side enforcement of rolling 24-hour token budgets.
|
Package budget provides agent-side enforcement of rolling 24-hour token budgets. |
|
controller
Package controller contains helpers for creating and managing KEDA ScaledObjects.
|
Package controller contains helpers for creating and managing KEDA ScaledObjects. |
|
mcpgateway
Package mcpgateway implements the ark MCP gateway — an http.Handler that exposes ArkAgent capabilities as callable MCP tools over the standard SSE transport.
|
Package mcpgateway implements the ark MCP gateway — an http.Handler that exposes ArkAgent capabilities as callable MCP tools over the standard SSE transport. |
|
routing
Package routing provides LLM-driven capability dispatch for ArkTeam routed mode.
|
Package routing provides LLM-driven capability dispatch for ArkTeam routed mode. |
|
webhook
Package webhook provides admission webhooks for ARKONIS CRDs.
|
Package webhook provides admission webhooks for ARKONIS CRDs. |
|
pkg
|
|
|
agent/providers
Package providers defines the LLMProvider interface and a self-registration registry.
|
Package providers defines the LLMProvider interface and a self-registration registry. |
|
agent/providers/anthropic
Package anthropic implements LLMProvider for the Anthropic Claude API.
|
Package anthropic implements LLMProvider for the Anthropic Claude API. |
|
agent/providers/gemini
Package gemini implements LLMProvider for Google Gemini models.
|
Package gemini implements LLMProvider for Google Gemini models. |
|
agent/providers/mock
Package mock provides a deterministic LLMProvider for local testing.
|
Package mock provides a deterministic LLMProvider for local testing. |
|
agent/providers/openai
Package openai implements LLMProvider for OpenAI-compatible APIs.
|
Package openai implements LLMProvider for OpenAI-compatible APIs. |
|
agent/queue
Package queue defines the pluggable interfaces for task distribution and real-time token streaming used by both the operator and the agent runtime.
|
Package queue defines the pluggable interfaces for task distribution and real-time token streaming used by both the operator and the agent runtime. |
|
agent/queue/redis
Package redis registers Redis Streams-backed implementations of TaskQueue and StreamChannel.
|
Package redis registers Redis Streams-backed implementations of TaskQueue and StreamChannel. |
|
artifacts
Package artifacts provides a pluggable interface for storing and retrieving file artifacts produced by pipeline steps.
|
Package artifacts provides a pluggable interface for storing and retrieving file artifacts produced by pipeline steps. |
|
costs
Package costs provides a pluggable cost translation layer for ark.
|
Package costs provides a pluggable cost translation layer for ark. |
|
costs/memstore
Package memstore provides an in-memory SpendStore for local development, ark run, and unit tests.
|
Package memstore provides an in-memory SpendStore for local development, ark run, and unit tests. |
|
costs/redisstore
Package redisstore registers a Redis-backed SpendStore.
|
Package redisstore registers a Redis-backed SpendStore. |
|
flow
Package flow contains pure business logic for ArkTeam DAG execution.
|
Package flow contains pure business logic for ArkTeam DAG execution. |
|
observability
Package observability — k8sevents.go provides a best-effort Kubernetes Event emitter for agent pods.
|
Package observability — k8sevents.go provides a best-effort Kubernetes Event emitter for agent pods. |
|
validation
Package validation provides helpers for step output validation, including semantic (LLM-based) validation for the ArkRun controller and ark run CLI.
|
Package validation provides helpers for step output validation, including semantic (LLM-based) validation for the ArkRun controller and ark run CLI. |
|
runtime
|
|
|
agent
command
|
|
|
test
|
|
Click to show internal directories.
Click to hide internal directories.