Distinguish sandboxes, runtimes, and code interpreters
Distinguish the security boundary, process runtime, and interpreter session when designing Polyaxon code execution for AI agents.
A sandbox, runtime, and code interpreter can appear in the same agent workflow, but they are not interchangeable. Each describes a different part of execution.
Keeping the terms precise helps you choose a Polyaxon workload, understand what state survives, and avoid promising an isolation boundary that the application does not actually provide.
Start with three separate questions
| Concept | Question it answers | Example |
|---|---|---|
| Sandbox boundary | What can the program access or affect? | Workload identity, mounts, network and runtime restrictions |
| Runtime | What executes the program? | Python process and its installed dependencies |
| Interpreter session | What interactive language state persists? | A notebook kernel retaining variables across cells |
An interpreter can run inside a constrained environment, but a restricted Python namespace is not by itself a complete security boundary. A container can run a Python process without providing a persistent notebook session.
In Polyaxon, sandbox access exposes process and filesystem operations inside a service's main container. It does not automatically add a separate kernel or a stateful language interpreter.
Match the interface to the agent's work
If the agent writes a file and runs it, command execution may be sufficient. Each invocation can read the same workspace while starting a fresh process.
If the workflow requires repeatedly modifying an in-memory dataframe, it needs an application-managed interpreter session or notebook kernel. Review notebook usage and define kernel startup, ownership, reset, and failure behavior.
If the work is a stable batch calculation, a Polyaxon job may be simpler than keeping a service and interpreter available. Package its inputs, code, and outputs as an ordinary reproducible component.
Identify the real isolation controls
The effective boundary comes from the workload's image, user, mounted volumes, credentials, Kubernetes identity, network policy, and runtime configuration.
Use connections only where needed. Keep broad provider or platform credentials in a trusted controller when the executed program has no reason to use them.
A tool schema can reject malformed arguments, but it cannot prevent an arbitrary program from using permissions already available inside its environment. Enforce mandatory restrictions outside that program.
Define state and failure semantics explicitly
For every interface, document what survives a completed command, a disconnected client, a restarted interpreter, and a replaced Pod.
The quick-start workspace uses emptyDir, which lasts for the Pod's lifetime. It can retain files across commands but not across Pod replacement. A long-running process may retain variables only while that process remains alive.
Use artifact persistence for outputs that must survive cleanup. Keep durable task records in an appropriate application store rather than relying on a terminal session as the system of record.
Give callers one clear execution contract
Return request identity, completion status, exit or interpreter error information, and approved output references. Explain whether cancellation stops one process, one interpreter, or the entire service.
Use Polyaxon tracking to connect the execution to its inputs and evaluation result. Record the environment and interface revision so comparisons use equivalent semantics.
Precise terminology is useful because it leads to precise behavior. Choose the runtime for compatibility, the session model for state, and the infrastructure controls for the required security boundary.