mirror of
https://github.com/harivansh-afk/agentikube.git
synced 2026-04-16 14:01:05 +00:00
140 lines
4.9 KiB
Markdown
140 lines
4.9 KiB
Markdown
# agentikube
|
|
|
|
[](https://github.com/harivansh-afk/agentikube/releases)
|
|
[](https://github.com/harivansh-afk/agentikube/releases)
|
|
[](https://github.com/harivansh-afk/agentikube)
|
|
[](https://github.com/harivansh-afk/agentikube/blob/main/go.mod)
|
|
[](https://github.com/harivansh-afk/agentikube)
|
|
|
|
This repo is a small Go CLI for running isolated agent sandboxes on Kubernetes.
|
|
|
|
The main job of `agentikube` is:
|
|
- set up shared sandbox infra (`init`, `up`)
|
|
- create one sandbox per user/handle (`create`)
|
|
- let you inspect and access sandboxes (`list`, `status`, `ssh`)
|
|
- clean up sandboxes or shared infra (`destroy`, `down`)
|
|
|
|
It is built for AWS-style setups (EFS + optional Karpenter).
|
|
|
|
## What This Stands Up
|
|
|
|
When you run `up`, it renders and applies Kubernetes manifests from templates.
|
|
|
|
Core resources:
|
|
- `Namespace`
|
|
- `StorageClass` (`efs-sandbox`, provisioner `efs.csi.aws.com`)
|
|
- `SandboxTemplate` (`sandbox-template`)
|
|
|
|
Optional resources:
|
|
- `SandboxWarmPool` (if `sandbox.warmPool.enabled: true`)
|
|
- `NodePool` + `EC2NodeClass` (if `compute.type: karpenter`)
|
|
|
|
When you run `create <handle>`, it creates:
|
|
- `Secret` (`sandbox-<handle>`) with provider credentials
|
|
- `SandboxClaim` (`sandbox-<handle>`) that points to `sandbox-template`
|
|
- PVC from template (`workspace` volume claim template)
|
|
|
|
## Filesystem
|
|
|
|
```text
|
|
cmd/agentikube/main.go # CLI entrypoint + subcommand wiring
|
|
internal/config/ # config structs + validation/defaults
|
|
internal/manifest/ # template rendering
|
|
internal/manifest/templates/ # Kubernetes YAML templates
|
|
internal/kube/ # kube client, apply, wait, exec helpers
|
|
internal/commands/ # command implementations
|
|
agentikube.example.yaml # example config you copy to agentikube.yaml
|
|
Makefile # build/install/fmt/vet targets
|
|
```
|
|
|
|
## How It Works (Simple Flow)
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
A[agentikube command] --> B[Load agentikube.yaml]
|
|
B --> C[Validate config + apply defaults]
|
|
C --> D{Command}
|
|
D -->|init| E[Install CRDs + check prereqs + ensure namespace]
|
|
D -->|up| F[Render templates -> server-side apply]
|
|
D -->|create| G[Create Secret + SandboxClaim]
|
|
G --> H[Watch SandboxClaim until Ready]
|
|
D -->|list/status| I[Read SandboxClaim/WarmPool state]
|
|
D -->|ssh| J[Resolve pod name -> kubectl exec -it]
|
|
D -->|destroy| K[Delete SandboxClaim + Secret + best-effort PVC]
|
|
D -->|down| L[Delete warm pool + template, keep user sandboxes]
|
|
```
|
|
|
|
## Resource Diagram (Abilities + Resources)
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
CLI[agentikube CLI] --> K8S[Kubernetes API]
|
|
CLI --> KUBECTL[kubectl binary]
|
|
|
|
K8S --> NS[Namespace]
|
|
K8S --> SC[StorageClass efs-sandbox]
|
|
K8S --> ST[SandboxTemplate]
|
|
K8S --> WP[SandboxWarmPool]
|
|
K8S --> NP[NodePool]
|
|
K8S --> ENC[EC2NodeClass]
|
|
|
|
K8S --> CLAIM[SandboxClaim per user]
|
|
K8S --> SECRET[Secret per user]
|
|
CLAIM --> POD[Sandbox Pod]
|
|
POD --> PVC[Workspace PVC]
|
|
PVC --> SC
|
|
SC --> EFS[(AWS EFS)]
|
|
|
|
NP --> EC2[(EC2 nodes via Karpenter)]
|
|
ENC --> EC2
|
|
```
|
|
|
|
## Commands
|
|
|
|
- `agentikube init`
|
|
Installs agent-sandbox CRDs, checks for EFS CSI/Karpenter, and ensures namespace exists.
|
|
- `agentikube up [--dry-run]`
|
|
Renders manifests and applies them with server-side apply. `--dry-run` prints YAML only.
|
|
- `agentikube create <handle> --provider <name> --api-key <key>`
|
|
Creates per-user Secret + SandboxClaim and waits (up to 3 minutes) for Ready.
|
|
- `agentikube list`
|
|
Shows handle, status, age, and pod name for all sandbox claims.
|
|
- `agentikube ssh <handle>`
|
|
Finds the sandbox pod and opens `/bin/sh` using `kubectl exec -it`.
|
|
- `agentikube destroy <handle> [--yes]`
|
|
Deletes SandboxClaim + Secret + best-effort PVC for that handle.
|
|
- `agentikube down`
|
|
Deletes shared warm pool/template infra but preserves existing user sandboxes.
|
|
- `agentikube status`
|
|
Prints warm pool numbers, sandbox count, and Karpenter node count (if enabled).
|
|
|
|
## Quick Start
|
|
|
|
1. Copy config:
|
|
|
|
```bash
|
|
cp agentikube.example.yaml agentikube.yaml
|
|
```
|
|
|
|
2. Fill your values in `agentikube.yaml`:
|
|
- namespace
|
|
- EFS filesystem ID / base path
|
|
- sandbox image
|
|
- compute settings
|
|
|
|
3. Run:
|
|
|
|
```bash
|
|
agentikube init
|
|
agentikube up
|
|
agentikube create demo --provider openai --api-key <key>
|
|
agentikube list
|
|
agentikube ssh demo
|
|
```
|
|
|
|
## Notes / Current Limits
|
|
|
|
- `storage.type` currently must be `efs`.
|
|
- `kubectl` must be installed (used by `init` and `ssh`).
|
|
- `compute.type: fargate` is validated, but this repo currently renders templates for the Karpenter path.
|
|
- No Go tests are present yet (`go test ./...` reports no test files).
|