# Notebooks

Valohai Notebooks give you cloud, or onprem-hosted, Jupyter environments running on your own infrastructure. Launch a notebook, run it on a GPU or CPU machine, and experiment freely, no local setup required.

Notebooks are built for **experimentation and exploration**, not production. When you're ready to scale, version, or schedule your work, convert your notebook to Git-versioned code and run it as standard executions.

### What You Get

Every Valohai Notebook execution gives you:

* **Your infrastructure, your choice**: Run on any environment your organization has configured: AWS auto-scale machines, Kubernetes nodes, on-premise GPUs, or cloud CPUs.
* **Dependency flexibility**: Use your own packages and Docker images. Valohai installs Jupyter automatically if it's not included.
* **Cloud storage access**: Pull data from your configured data stores directly into the notebook using Valohai inputs.
* **Git integration**: Push changes back to your Git-repository when you're ready.
* **Instant sharing**: Share notebook URLs with teammates without environment setup.

### When to Use Notebooks

**Good for:**

* Early-stage exploration and prototyping
* Debugging failed executions by reproducing their environment
* One-off analyses or data investigations
* Testing new libraries or approaches interactively

**Not good for:**

* Production workflows or scheduled jobs
* Pipelines or multi-step processes
* Hyperparameter tuning at scale (use [Tasks](/tasks.md) instead)
* Long-running training jobs (use [Executions](/executions.md) instead)

Notebooks don't keep machines warm between sessions. Expect 2–5 minute startup times depending on your environment. If you need instant access, you can keep a notebook running, but you'll pay for idle time.

### The Workflow

Here's the typical notebook journey on Valohai:

1. **Launch** a notebook with your chosen environment and data inputs
2. **Experiment** interactively, install packages, test code, visualize results
3. **Save** your work (outputs are automatically versioned)
4. **Convert** your notebook to a standard execution using `valohai.prepare()` and "Run Remote"
5. **Productionize** by defining your job in `valohai.yaml` and running it as a standard execution

Once your code is in `valohai.yaml`, you can run it at scale, schedule it, chain it into pipelines, or launch hyperparameter sweeps.

### Cost Considerations

Notebooks run on real machines, they're not "always ready" like a SaaS notebook service. This design keeps costs down when you're not actively working.

**Key points:**

* You pay your cloud provider for the machine while the notebook is running, even if idle
* Stopping a notebook releases the machine and stops billing
* Restarting requires spinning up a new machine (2–5 minutes)
* Always stop notebooks when you're done

See [Manage Notebook Lifecycle](/notebook-executions/stop-restart.md) for details on managing costs and startup times.

### Next Steps

* [Launch Your First Notebook](/notebook-executions/quickstart.md) — Get a notebook running in 3 minutes
* [Convert to Production Script](/notebook-executions/notebook-to-execution.md) — Move from experimentation to execution


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.valohai.com/notebook-executions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.