Code Interpreter

Use the code-interpreter template when you want notebook-style execution inside a hosted machine. It adds stateful cells, package installation, stdout/stderr callbacks, structured results, artifacts, and language contexts on templates that include them. Use raw Commands instead when you only need a process to run and return stdout or stderr.

Quick Example

from nullspace import Machine

with Machine.create(template="code-interpreter", timeout=120) as machine:
    execution = machine.run_code("x = 40 + 2\nx")
    print(execution.results[0].text)

import { Machine } from "@nullspace/sdk";

const machine = await Machine.create({ template: "code-interpreter", timeout: 120 });
const execution = await machine.code.run("x = 40 + 2\nx");
console.log(execution.results[0].text);
await machine.destroy();

nullspace machine code run mch_123 "x = 40 + 2
x"

# returns a Server-Sent Events stream of JSON events
curl -N -X POST "${NULLSPACE_API_URL}/v1/machines/mch_123/code/execute" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" -d '{"code": "x = 40 + 2\nx"}'

When To Use It

Need	Use Code Interpreter?
Keep variables between cells	Yes. Use contexts to preserve kernel state.
Return rich results or downloadable artifacts	Yes. Results can include text, images, HTML, and files.
Stream stdout and stderr during execution	Yes. Use callbacks or streaming APIs.
Run a normal CLI command or service	Usually no. Use Commands instead.
Preinstall a repeatable analysis stack	Build a custom template and use it with Code Interpreter.

Core Concepts

Concept	Meaning
Template	`code-interpreter` includes the runtime for notebook-style execution.
Context	A stateful kernel namespace that can keep variables and imports warm.
Run	One code execution request, with logs, results, artifacts, and errors.
Artifact	A generated file or rich output your app can inspect or download.

Package Installs

machine.install_packages(["humanize==4.9.0"])
result = machine.run_code(
    "import humanize\nprint(humanize.intword(1234567))"
)
print("".join(result.logs.stdout))

nullspace machine code install mch_123 humanize==4.9.0
nullspace machine code run mch_123 "import humanize
print(humanize.intword(1234567))"

# install_packages runs a pip command through the code interpreter
# returns a Server-Sent Events stream of JSON events
curl -N -X POST "${NULLSPACE_API_URL}/v1/machines/mch_123/code/execute" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"code": "!pip install humanize==4.9.0"}'

Package installs affect the running machine. Use Templates when the same libraries should be available on every create.

Rich Output

plot = machine.run_code("""
import matplotlib.pyplot as plt
plt.plot([1, 2, 3], [1, 4, 9])
plt.show()
""")

has_png = any(
    result.png or (result.data and "image/png" in result.data)
    for result in plot.results
)
print(has_png)

Rich result objects (result.png, result.data, captured plt.show() output) are SDK-only. Via the CLI or HTTP API, save the figure to a file and fetch it with code artifact download or a filesystem read.

Guides

Analyze data with AI

Run stateful Python, R, JavaScript, TypeScript, Java, or Bash cells.

Charts and visualizations

Generate static charts, interactive HTML outputs, and downloadable files.

Supported languages

Choose a kernel and keep state in language-specific contexts.

Streaming

Stream stdout, stderr, results, artifacts, and errors as code executes.

Get started

Machines

Commands

Filesystem

Desktop

Templates

Volumes

Networking

Interactive access

Observability

Code Interpreter

Quick Example

When To Use It

Core Concepts

Package Installs

Rich Output

Guides

Analyze data with AI

Charts and visualizations

Supported languages

Streaming

​Quick Example

​When To Use It

​Core Concepts

​Package Installs

​Rich Output

​Guides

Analyze data with AI

Charts and visualizations

Supported languages

Streaming

​Related

Quick Example

When To Use It

Core Concepts

Package Installs

Rich Output

Guides

Related