agentikube/README.md

agentikube

A Helm package used for spinning up isolated stateful agent sandboxes via k8 pods

What it does

• init - Installs CRDs, checks prerequisites, ensures your namespace exists
• up - Renders and applies Kubernetes manifests from templates (--dry-run to preview)
• create <handle> - Spins up a sandbox for a user with provider credentials
• list - Shows all sandboxes with status, age, and pod name
• status - Warm pool numbers, sandbox count, Karpenter node count
• ssh <handle> - Drops you into a sandbox pod shell
• destroy <handle> - Tears down a single sandbox
• down - Removes shared infra but keeps existing user sandboxes

Quick start

Option A: Helm chart

# 1. Create your values file
cat > my-values.yaml <<EOF
compute:
  clusterName: my-eks-cluster
storage:
  filesystemId: fs-0123456789abcdef0
sandbox:
  image: my-registry/sandbox:latest
EOF

# 2. Install
helm install agentikube ./chart/agentikube \
  -n sandboxes --create-namespace \
  -f my-values.yaml

# 3. Create a sandbox and jump in
agentikube create demo --provider openai --api-key <key>
agentikube ssh demo

Option B: CLI only

# 1. Copy and fill in your config
cp agentikube.example.yaml agentikube.yaml
# Edit: namespace, EFS filesystem ID, sandbox image, compute settings

# 2. Set things up
agentikube init
agentikube up

# 3. Create a sandbox and jump in
agentikube create demo --provider openai --api-key <key>
agentikube list
agentikube ssh demo

What gets created

Running up applies these to your cluster:

• Namespace, StorageClass (efs-sandbox), SandboxTemplate
• Optionally: SandboxWarmPool, NodePool + EC2NodeClass (Karpenter)

Running create <handle> adds:

• A Secret and SandboxClaim per user
• A workspace PVC backed by EFS

Project layout

cmd/agentikube/main.go         # entrypoint
internal/config/               # config structs + validation
internal/manifest/             # template rendering
internal/manifest/templates/   # k8s YAML templates (used by CLI)
internal/kube/                 # kube client helpers
internal/commands/             # command implementations
chart/agentikube/              # Helm chart
scripts/                       # helper scripts (CRD download)
agentikube.example.yaml        # example config
Makefile                       # build/install/fmt/vet/helm

Build and test locally

go build ./...
go test ./...
go run ./cmd/agentikube --help

# Smoke test manifest generation
./agentikube up --dry-run --config agentikube.example.yaml

Good to know

• storage.type is efs only for now
• kubectl needs to be installed (used by init and ssh)
• Fargate is validated in config but templates only cover the Karpenter path so far
• No Go tests written yet - go test passes but reports no test files
• k9s is great for browsing sandbox resources (brew install derailed/k9s/k9s)

Context