KubernetesPodSandbox

pydantic_ai_backends.backends.kubernetes.KubernetesPodSandbox

Bases: BaseSandbox

Sandbox backed by a Kubernetes pod.

Parameters:

Name	Type	Description	Default
image	str	container image to run.	required
namespace	str	K8s namespace to create the pod in.	'default'
sandbox_id	str | None	identifier; used as a deterministic pod name suffix, sanitized to DNS-1123. Auto-generated if not provided.	None
session_id	str | None	alias for sandbox_id (accepted for parity with DockerSandbox). Ignored if sandbox_id is set.	None
mode	Literal['http', 'api']	"http" (default) talks to an in-pod exec server on port; "api" uses the K8s pods/exec subresource. mode="api" shells out as timeout <n> sh -c <command>, so the image must provide /bin/sh and a timeout binary (GNU coreutils or the BusyBox applet). Stock images such as python:*, node:*, debian, ubuntu and alpine all ship it; minimal/distroless images without a shell do not and will surface timeout: not found.	'http'
port	int	port the in-pod exec server listens on (mode="http" only).	DEFAULT_PORT
exec_token	str | None	shared secret sent in the X-Sandbox-Token header (mode="http" only). Auto-generated if not provided; written into the pod env as SANDBOX_EXEC_TOKEN.	None
pod_template	dict[str, Any] | None	optional dict — full pod spec body. If set, used verbatim (with image / env / labels filled in). Otherwise a sensible default is built (single container, non-root, readOnlyRootFilesystem, 768Mi/1CPU limit).	None
kube_config_path	str | None	path to a kubeconfig. If unset, falls back to in-cluster config, then ~/.kube/config.	None
in_cluster	bool | None	force in-cluster vs out-of-cluster auth.	None
startup_timeout	int	seconds to wait for Ready in start().	DEFAULT_STARTUP_TIMEOUT
idle_timeout	int	passed through to SessionManager for parity.	3600
labels	dict[str, str] | None	extra labels merged into the pod metadata.	None
env	dict[str, str] | None	extra environment variables for the container.	None
delete_on_stop	bool	whether stop() deletes the pod. Default True.	True
service_account_name	str	serviceAccountName for the pod (defaults to default; recommend a dedicated, no-privilege SA).	'default'

Lifecycle

• __init__ validates args and builds the in-memory client. It does not create the pod — call start() (or let SessionManager.get_or_create() call it) to actually create.
• start() creates the pod and blocks until Ready.
• execute(), edit(), read(), write(), glob_info, grep_raw, ls_info: synchronous, talk to the pod (HTTP or pods/exec) and return.
• stop() deletes the pod (if delete_on_stop=True); idempotent; never raises.

Errors

• Constructor raises ImportError if the kubernetes SDK is not installed (pip install pydantic-ai-backend[kubernetes]).
• start() raises RuntimeError if the pod doesn't reach Ready in startup_timeout.
• execute() never raises; runtime errors are surfaced as ExecuteResponse(output="Error: ...", exit_code=1).

__init__(image, *, namespace='default', sandbox_id=None, session_id=None, mode='http', port=DEFAULT_PORT, exec_token=None, pod_template=None, kube_config_path=None, in_cluster=None, startup_timeout=DEFAULT_STARTUP_TIMEOUT, idle_timeout=3600, labels=None, env=None, delete_on_stop=True, service_account_name='default')

start()

Create the pod and wait for it to be Ready.

stop()

is_alive()

execute(command, timeout=None)

edit(path, old_string, new_string, replace_all=False)

read(path, offset=0, limit=2000)

write(path, content)

ls_info(path)

glob_info(pattern, path='/')