Add a code interpreter to an AI app by routing model-requested code execution into an isolated sandbox with scoped files, a clear package policy, resource and time limits, captured outputs, and application-side review before results are shown or persisted. The model can decide when code is useful, but your app should own the execution boundary: upload only the files needed for the task, create or reuse a short-lived sandbox session, run Python with strict limits, capture stdout, stderr, generated files, and logs, return a structured result to the model, and clean up the session when the workflow is done.
What a code interpreter adds to an AI app
A code interpreter turns a language model from a text-only assistant into a tool-using application that can calculate, transform files, inspect data, generate charts, and produce reviewable artifacts. Instead of asking the model to reason about a spreadsheet from a prompt, the app can let the model write Python, run it against the uploaded file, inspect the output, and explain the result.
The useful pattern is not “let the model run anything.” The useful pattern is controlled execution. Your application accepts a user task, lets the model request a tool call such as run_python, and then executes that request inside a sandbox rather than in the main application process. The sandbox becomes the workbench for temporary files, package installs, scripts, charts, and logs.
Code interpreter features are especially useful for:
- CSV, Excel, JSON, and log analysis
- chart generation from uploaded data
- format conversion and data cleaning
- math and simulation tasks that need exact computation
- code snippets that need to be tested before the model explains them
- multi-step agent workflows where outputs from one step become inputs to the next
They are a poor fit for tasks that require unrestricted production credentials, long-lived access to private systems, or silent execution with no user-visible audit trail. If the result can affect money, infrastructure, safety, or access control, add review gates before any side effect leaves the sandbox.
Reference architecture
A practical code interpreter architecture has five parts:
| Layer | Responsibility | Common design choice |
|---|---|---|
| User interface | Upload files, show progress, display artifacts, request approval | Keep uploaded files scoped to the current conversation or project |
| Application server | Authenticate users, enforce policy, create sandbox sessions, store logs | Never expose raw sandbox credentials to the browser |
| Model orchestration | Decide when to call code tools and summarize results | Use structured tool calls rather than parsing free-form text |
| Sandbox runtime | Execute Python, hold temporary files, install allowed packages | Run with resource, timeout, and cleanup controls |
| Artifact store | Preserve approved outputs such as charts, CSVs, reports, and logs | Store only outputs the app or user has accepted |
The model should not directly control infrastructure. It should ask for a tool call. Your application decides whether that tool call is allowed, which files are attached, how long it may run, which packages are available, and which outputs are returned.
That separation keeps the model useful without making it the security boundary.
Implementation flow
A strong implementation flow starts before any code is executed.
1. Accept the user task and files
When the user uploads a file, store it under an application-level file record with owner, workspace, content type, size, and retention policy. Do not immediately expose every file in the user’s account to the interpreter. The sandbox should receive only the files needed for the current task.
For example, a user might ask:
“Analyze this CSV, find the top revenue drivers, and return a chart plus a short explanation.”
Your app can attach the uploaded CSV to the next model turn as an available file, but the actual file bytes should move into the sandbox only when code execution is approved.
2. Let the model request a tool call
Define a narrow tool surface. A typical first version needs only a few tools:
{
"name": "run_python",
"arguments": {
"code": "import pandas as pd\n...",
"input_files": ["sales.csv"],
"expected_outputs": ["summary.json", "revenue_chart.png"],
"timeout_seconds": 30
}
}Keep the schema explicit. The model should declare the code, input files, expected outputs, and a timeout request. The application can shorten the timeout, reject unknown files, or block commands that conflict with policy.
3. Create or reuse a sandbox session
For a one-shot assistant response, create a fresh sandbox session, upload the input files, run the code, collect the result, and terminate the session. For a notebook-like user experience, keep a session alive for the current conversation so later cells can reuse prior variables and files.
Short-lived sessions are easier to reason about. Stateful sessions are more ergonomic for analysis tasks. Pick deliberately and show the user when state exists.
4. Execute Python and capture results
Run code through the sandbox execution API or your own worker inside the sandbox. Capture structured execution output:
{
"status": "success",
"stdout": "Loaded 12,448 rows\n",
"stderr": "",
"artifacts": [
{
"path": "revenue_chart.png",
"type": "image/png",
"size_bytes": 84231
},
{
"path": "summary.json",
"type": "application/json",
"size_bytes": 1260
}
],
"duration_ms": 1840
}Return this structured result to the model. The model can then explain what happened, cite the generated files, and ask whether the user wants another pass.
5. Return results to the user
Do not force the user to read raw logs unless something failed. A good interface shows the answer, the generated chart or file, and a small disclosure that code was executed. Provide an expandable execution log for review.
For failed executions, show a concise error and let the model revise the code. Avoid dumping long tracebacks into the main chat unless the user is debugging.
Handle files, outputs, and generated artifacts
File handling is where many code interpreter projects become messy. Treat inputs and outputs as separate objects.
Input files should be copied into the sandbox under stable, sanitized paths. Avoid preserving user-supplied path names that contain spaces, shell characters, or nested directories. Keep a mapping from display name to sandbox path in application state.
Generated files should be scanned and classified before they become downloadable artifacts. A chart image, cleaned CSV, JSON summary, or PDF report may be safe to present directly. A generated script, executable file, or archive should require stricter handling.
For chart generation, ask the model to save image files explicitly instead of relying only on inline display. For data analysis, ask for a machine-readable summary file as well as natural-language explanation. That gives your app something stable to validate and store.
A useful artifact policy looks like this:
| Artifact type | Default handling |
|---|---|
.png, .jpg, .webp, .svg charts | Preview in the UI after size and type checks |
.csv, .json, .xlsx data outputs | Offer as downloads and summarize changes |
.txt, .md, .pdf reports | Preview or download depending on size |
.py, .sh, binaries, archives | Do not auto-run or auto-open; require explicit review |
If your app supports persistent projects, store accepted artifacts outside the sandbox. The sandbox should remain disposable.
Set package and network policy
Most code interpreter workflows need packages such as pandas, NumPy, matplotlib, seaborn, scikit-learn, or openpyxl. The question is whether packages are preinstalled, installed on demand, or built into custom sandbox templates.
Preinstalled packages keep execution predictable. On-demand installs are flexible but can slow down tasks and introduce dependency drift. Custom templates are usually the best production path once you know your common workloads.
Set a package policy before launch:
- which packages are always available
- whether the model may request package installs
- whether installs can reach public package indexes
- whether version pins are required
- how long installs may run
- whether compiled or native packages are allowed
Network policy matters just as much. Many data tasks do not need internet access after files are uploaded. If a workflow does need external APIs, route credentials through application-approved tools instead of dropping broad secrets into the sandbox. The model should not receive unrestricted environment variables by default.
Apply limits, logs, cleanup, and review
A code interpreter is a production feature, not a demo cell runner. Put limits around it from the start.
Minimum controls should include:
- maximum execution time per cell or tool call
- maximum output size for stdout and stderr
- maximum artifact size and file count
- CPU and memory limits appropriate for the task
- allowed file extensions for preview and download
- per-user and per-workspace concurrency limits
- cleanup rules for temporary sessions and files
Logs should answer three questions: who requested execution, what code ran, and what outputs were produced. Store enough to debug and audit the workflow, but avoid retaining private uploaded data longer than your product policy requires.
Human or user review is the final control. For low-risk analysis, review may mean the user sees the chart before downloading it. For agent workflows that can update tickets, write to databases, or call external APIs, review should happen before the side effect, not after.
Where Novita Agent Sandbox fits
Novita Agent Sandbox is designed for AI agents that need isolated runtime environments for code execution, browser workflows, computer-use style tasks, evaluations, reinforcement learning environments, and long-running workflows. For a code interpreter feature, that means the sandbox can serve as the execution layer while your app remains responsible for user auth, model orchestration, file policy, review, and product-specific retention.
Novita’s sandbox documentation includes filesystem workflows for reading, writing, uploading, downloading, and watching files in a sandbox. Those capabilities map directly to code interpreter needs: move user files into the execution environment, let code generate charts or transformed data, then bring selected outputs back to the app. See the Novita sandbox filesystem documentation for the current file-operation overview.
If your interpreter grows beyond a simple Python runner, custom sandbox templates can help standardize dependencies and runtime setup. That is useful when every session needs the same analysis stack, internal command-line tools, or project-specific libraries. Start with a small allowed package set, then move repeated setup into templates once the workload stabilizes.
Keep Novita-specific integration decisions separate from the general architecture. Your code interpreter still needs application-level policies for file visibility, package installation, network access, log retention, and review. The sandbox provides the controlled runtime; your product defines how that runtime is used.
Evaluation checklist
Before shipping, test the feature with real workflows and adversarial prompts.
| Question | What to verify |
|---|---|
| Can users upload the right files? | File size, type checks, owner checks, and clear error messages |
| Can the model request execution cleanly? | Structured tool calls with code, inputs, expected outputs, and timeout |
| Is the sandbox scoped correctly? | Only approved files and environment variables are available |
| Are packages predictable? | Common packages work, denied packages fail clearly, installs have limits |
| Are outputs usable? | Charts render, files download, summaries match generated artifacts |
| Are failures recoverable? | Tracebacks are captured, the model can revise code, users see concise errors |
| Are limits enforced? | Infinite loops, huge outputs, memory-heavy tasks, and long installs terminate |
| Is review built in? | Users can inspect code, logs, and artifacts before important side effects |
| Is cleanup reliable? | Temporary files and sessions are removed or expired on schedule |
The best first release is usually narrow: Python execution, a small package set, file upload, charts and downloadable files, clear limits, and an execution log. Add broader package installs, persistent sessions, external API access, and agentic side effects only after the basic loop is observable and reliable.
Conclusion
A code interpreter works best when the model can ask for execution, but your app controls the sandbox, files, limits, and review step. Start with a narrow Python tool, keep inputs and outputs explicit, and expand only after the flow is stable.
FAQ
What is the safest way to add a code interpreter?
Use an isolated sandbox, scope the input files, cap runtime and memory, and return structured outputs instead of raw shell access.
Should the model control package installs?
Only within a policy you define. Many apps start with a fixed package set and add installs later if the workload needs them.
Do all code interpreter tasks need network access?
No. Many analysis workflows work fully offline once the user files are uploaded, which keeps the execution model simpler.
What should the user see after execution?
The result, generated artifacts, and a concise log or error summary, with the option to inspect code or rerun the task.
