> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt
> Use this file to discover all available pages before exploring further.

# Code Interpreter

> Run stateful notebook-style code with structured results and artifacts.

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](../commands/overview) instead when you only need a process
to run and return stdout or stderr.

## Quick Example

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  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)
  ```

  ```typescript TypeScript SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  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();
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine code run mch_123 "x = 40 + 2
  x"
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  # 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"}'
  ```
</CodeGroup>

## 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

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  machine.install_packages(["humanize==4.9.0"])
  result = machine.run_code(
      "import humanize\nprint(humanize.intword(1234567))"
  )
  print("".join(result.logs.stdout))
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine code install mch_123 humanize==4.9.0
  nullspace machine code run mch_123 "import humanize
  print(humanize.intword(1234567))"
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  # 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"}'
  ```
</CodeGroup>

Package installs affect the running machine. Use [Templates](../templates/overview)
when the same libraries should be available on every create.

## Rich Output

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
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

<CardGroup cols={2}>
  <Card title="Analyze data with AI" href="./analyze-data">
    Run stateful Python, R, JavaScript, TypeScript, Java, or Bash cells.
  </Card>

  <Card title="Charts and visualizations" href="./charts-overview">
    Generate static charts, interactive HTML outputs, and downloadable files.
  </Card>

  <Card title="Supported languages" href="./languages-overview">
    Choose a kernel and keep state in language-specific contexts.
  </Card>

  <Card title="Streaming" href="./streaming">
    Stream stdout, stderr, results, artifacts, and errors as code executes.
  </Card>
</CardGroup>

## Related

* [Commands](../commands/overview)
* [Contexts](./contexts)
* [Runs and artifacts](./runs-artifacts)
* [Code Interpreter example](../examples/code-interpreter)