AgentSandbox

apiVersion

agents.nanohype.dev/v1alpha1

kind

AgentSandbox

scope

Namespaced

reconciled by

eks-agent-platform

short names

agsbx

AgentSandbox is a Platform-scoped, single-use isolated pod for one agent role-session. It shares SandboxPool's hardening — Pod Security "restricted", default-deny networked, on the dedicated tainted node pool — but is push-dispatched (one session, run-once) rather than a pull-based pool of always-on workers.

AgentSandboxSpec declares one ephemeral, hardened pod that runs a single agent role-session — fab's `sdk` role-loop dispatched per session. The reconciler builds the pod on the dedicated, tainted sandbox node pool, locked down by a default-deny NetworkPolicy, under the Platform's tenant ServiceAccount — which carries the tenant's AWS identity through its EKS Pod Identity association.

What kubectl get shows

Column	Type	Meaning
Platform	string	—
Phase	string	—
Pod	string	—

Spec

• imagestringrequired

  Image is the container image the session pod runs.

• platformRefobjectrequired

  PlatformRef is the owning Platform. The session pod runs in that Platform's tenant namespace and the sandbox gates on Platform readiness.

  • namestringrequired

• activeDeadlineSecondsinteger (int32)default 14400

  ActiveDeadlineSeconds is the wall-clock ceiling on one session, measured from the moment the pod starts. It is what makes TTLSecondsAfterFinished reachable. That TTL counts from a TERMINAL phase, so it collects a session that ended and says nothing about one that never does: a hung agent — a tool call waiting on a socket nothing will answer, a model call with no deadline of its own — leaves a pod holding its node slot and its tenant credentials indefinitely, polled every reconcile forever, with the garbage collector waiting on a phase that will not arrive. Kubernetes enforces this one itself and marks the pod Failed on expiry, which IS the terminal phase, so the existing TTL then collects it. The two fields are one mechanism: this bounds the session, that bounds the corpse. Default 4h — comfortably past any legitimate agent session and far short of a pod nobody notices for a week. Set 0 to disable, which is a decision about a specific workload rather than the shape a sandbox ships with.

• args[]string

  Args are the container arguments.

• command[]string

  Command overrides the image entrypoint.

• env[]object

  Env is the session pod's environment. The dispatcher (fab) passes the role, the role message, and any backend config through here.

  • namestringrequired

    Name of the environment variable. May consist of any printable ASCII characters except '='.

  • valuestring

    Variable references $(VAR_NAME) are expanded using the previously defined environment variables in the container and any service environment variables. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. "$$(VAR_NAME)" will produce the string literal "$(VAR_NAME)". Escaped references will never be expanded, regardless of whether the variable exists or not. Defaults to "".

  • valueFromobject

    Source for the environment variable's value. Cannot be used if value is not empty.

    5 fields under valueFrom

    • configMapKeyRefobject

      Selects a key of a ConfigMap.

      3 fields under configMapKeyRef

      • keystringrequired

        The key to select.

      • namestringdefault ""

        Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names

      • optionalboolean

        Specify whether the ConfigMap or its key must be defined

    • fieldRefobject

      Selects a field of the pod: supports metadata.name, metadata.namespace, `metadata.labels['<KEY>']`, `metadata.annotations['<KEY>']`, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs.

      2 fields under fieldRef

      • fieldPathstringrequired

        Path of the field to select in the specified API version.

      • apiVersionstring

        Version of the schema the FieldPath is written in terms of, defaults to "v1".

    • fileKeyRefobject

      FileKeyRef selects a key of the env file. Requires the EnvFiles feature gate to be enabled.

      4 fields under fileKeyRef

      • keystringrequired

        The key within the env file. An invalid key will prevent the pod from starting. The keys defined within a source may consist of any printable ASCII characters except '='. During Alpha stage of the EnvFiles feature gate, the key size is limited to 128 characters.

      • pathstringrequired

        The path within the volume from which to select the file. Must be relative and may not contain the '..' path or start with '..'.

      • volumeNamestringrequired

        The name of the volume mount containing the env file.

      • optionalbooleandefault false

        Specify whether the file or its key must be defined. If the file or key does not exist, then the env var is not published. If optional is set to true and the specified key does not exist, the environment variable will not be set in the Pod's containers. If optional is set to false and the specified key does not exist, an error will be returned during Pod creation.

    • resourceFieldRefobject

      Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported.

      3 fields under resourceFieldRef

      • resourcestringrequired

        Required: resource to select

      • containerNamestring

        Container name: required for volumes, optional for env vars

      • divisorobject

        Specifies the output format of the exposed resources, defaults to "1"

    • secretKeyRefobject

      Selects a key of a secret in the pod's namespace

      3 fields under secretKeyRef

      • keystringrequired

        The key of the secret to select from. Must be a valid secret key.

      • namestringdefault ""

        Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names

      • optionalboolean

        Specify whether the Secret or its key must be defined

• resourcesobject

  Resources are the session pod's resource requests and limits.

  • claims[]object

    Claims lists the names of resources, defined in spec.resourceClaims, that are used by this container. This field depends on the DynamicResourceAllocation feature gate. This field is immutable. It can only be set for containers.

    2 fields under claims

    • namestringrequired

      Name must match the name of one entry in pod.spec.resourceClaims of the Pod where this field is used. It makes that resource available inside a container.

    • requeststring

      Request is the name chosen for a request in the referenced claim. If empty, everything from the claim is made available, otherwise only the result of this request.

  • limitsobject

    Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

  • requestsobject

    Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. Requests cannot exceed Limits. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

• runtimeClassNamestring

  RuntimeClassName selects a Kubernetes RuntimeClass for the session pod — "gvisor" or "kata" for kernel-level isolation of the untrusted agent code. The named RuntimeClass must already exist. Empty uses the cluster's default runtime.

• ttlSecondsAfterFinishedinteger (int32)default 3600

  TTLSecondsAfterFinished is how long the AgentSandbox is kept after its session pod terminates before the operator garbage-collects it.

• writablePaths[]string

  WritablePaths are additional absolute paths the session container may write, mounted as emptyDir alongside /workspace and /tmp. The session runs with a read-only root filesystem, and the only paths this operator can name for an arbitrary image are the two it already mounts: /workspace, which is this CRD's own contract, and /tmp, which every runtime expects. Everything else is a fact about the image — where its user's HOME is, where its toolchain caches — and the image is yours. Declare what your entrypoint writes. Getting this wrong surfaces as the container failing on a read-only filesystem at the moment it tries, which is inside a tool call rather than at startup, so it is worth checking against the image rather than discovering.