Sandbox setup

This reference covers the AKS setup used by the deployment scripts. The live in-cluster model is a single AgentHost warm pool managed by the upstream agent-sandbox controller.

Components

Component	Source	Purpose
agent-sandbox controller	scripts/azure/steps/10-create-cluster.mjs	Installs CRDs in API group extensions.agents.x-k8s.io.
SandboxTemplate/agentweaver-agent-host	k8s/base/sandbox-template-agenthost.yaml	Defines the Kata-isolated AgentHost pod: image, service account, workspace PVC, config, A2A port 8088.
SandboxWarmPool/agentweaver-agent-host	k8s/base/sandbox-warmpool-agenthost.yaml	Keeps AgentHost pods pre-warmed for fast run startup.
SandboxClaim	created per run by the API/worker	Binds one warm AgentHost pod for a run, then releases it on completion/suspend.

Install order

The canonical workflow provisions and deploys the sandbox pieces through the root package scripts (npm run shown; pnpm run is equivalent):

npm run azure:provision-infra      # installs the controller + CRDs, builds/pushes images, applies the template/warm pool, and verifies it

For an existing cluster, npm run azure:deploy-from-local builds/pushes images, redeploys, and cycles the warm pool without re-provisioning the cluster. azure:provision-infra/azure:deploy-from-local apply sandbox-template-agenthost.yaml before sandbox-warmpool-agenthost.yaml; the warm pool depends on the template by name. For targeted recovery, the AKS deployment runbook shows how to run individual steps, including gen-a2a-mtls-certs.

AgentHost pod behavior

1. Warm pods start without run context and wait in standby.
2. A run creates a SandboxClaim referencing warm pool agentweaver-agent-host.
3. The controller binds a warm pod and reports it in status.sandbox.name.
4. The API/worker calls AgentHost /configure with run/user/token context.
5. Agent turns run over A2A on port 8088.
6. Releasing the claim deletes the used pod; the warm pool replenishes it.

Per-run context is not injected through SandboxClaim.spec.env; as of controller v0.5.3 the warm-pool-adoption-bypass behavior tied to spec.env/spec.volumeClaimTemplates has not been confirmed fixed upstream (see the blocker analysis on #481) — static config stays in the template and configmap-agenthost.yaml until that is verified.

Required configuration

Setting	Value
Namespace	agentweaver by default (NAMESPACE)
AgentHost warm pool ref	agentweaver-agent-host
RuntimeClass	kata-vm-isolation
AgentHost image	${ACR_LOGIN_SERVER}/agentweaver-agent-host:${AGENTHOST_IMAGE_TAG}
Key Vault URI	https://${KEYVAULT_NAME}.vault.azure.net/
Workspace	PVC agentweaver-workspace, mounted at /workspace

The AgentHost image is built by npm run azure:deploy-from-local (or azure:provision-infra) from apps/Agentweaver.AgentHost/Dockerfile. It must publish with --runtime linux-x64 --self-contained false so the Copilot native runtime is included.

Verify

kubectl api-resources --api-group=extensions.agents.x-k8s.io
kubectl get runtimeclass kata-vm-isolation
kubectl get sandboxtemplate,sandboxwarmpool -n agentweaver
kubectl get pods -n agentweaver -l app.kubernetes.io/component=agent-host
npm run azure:verify

Expected resources:

sandboxtemplate.extensions.agents.x-k8s.io/agentweaver-agent-host
sandboxwarmpool.extensions.agents.x-k8s.io/agentweaver-agent-host

Troubleshooting

Symptom	Check
Warm pods do not appear	kubectl describe sandboxwarmpool agentweaver-agent-host -n agentweaver
Pods stay Pending	kubectl get runtimeclass, kubectl describe node, and katapool capacity
Image pull failure	image tag matches AGENTHOST_IMAGE_TAG and ACR is attached to AKS
/configure or A2A fails	NetworkPolicies allow API/worker to AgentHost TCP 8088; run npm run azure:verify
Token delivery fails	service account agentweaver-agent-host has workload identity federation to the dedicated agentweaver-agenthost-identity; the run owner's GitHub token is brokered by the API in /configure (gitHubAccessToken) — the sandbox identity has no Key Vault access (issue #471)