Retain / User Guide
Back to User Guide
Getting started

The notebook sandbox

Invalid Date
2 min read

Notebook code runs on your own Mac, inside a small Linux virtual machine that Retain starts for each notebook. Nothing runs on a Retain server, and the code can see only what you give it. This page explains where code runs, what it can reach, what downloads the first time, and which Mac app can do it.

Where code runs

Each notebook gets its own virtual machine on your Mac, using Apple's virtualization. The machine starts when you open a notebook that has code to run, and stops after 15 minutes idle. At most three notebooks run at once, and the least recently used idle one stops first to free memory, with a note that its variables were cleared.

What you see in the notebook, such as outputs, results and charts, syncs to your other devices. The code does not run on them. An iPhone shows a notebook but never runs it. See Notebooks: cells, Run and outputs.

What the code can see

  • Its own work folder at /work, one per notebook. A notebook cannot see another notebook's files or packages.
  • Your declared folders, read-only at /data. Code cannot change them.
  • Nothing else on your Mac. Your other files, your home folder and services running on your Mac are out of reach.

Each notebook's system is read-only, with a writable layer capped at 10 GB. Files you keep in /work stay when Python restarts or resets.

What the code can reach

The virtual machine has no network connection of its own. Its web requests go through a filter that Retain runs on your Mac, and the filter allows HTTPS to only a short list: PyPI for installing packages, and the hosts you add in Settings. It refuses addresses on your own network, including your Mac and other machines, so a notebook cannot be pointed at them. Tunnels you add are the one other way out. See Notebook setup and bringing data in.

If code ignores a request to stop, Retain restarts Python after 3 seconds and the run ends as interrupted.

What downloads the first time

The first time you run a notebook, Retain asks you to set up Python. The button shows the download size, which is a few hundred megabytes, and you need that much free disk space plus room to unpack it. It downloads once for every notebook, with progress, and it resumes if interrupted. After that the download is not repeated. Packages in your setup download when a notebook starts, and are kept for every notebook.

Setup needs no Docker and no cloud account.

Which Mac app has it

Notebooks run in Retain for Mac, from retainapp.ai. It needs macOS 26 or later on a Mac with Apple silicon. On other Macs notebooks can be read and edited but not run, and Run says so. See Installing Retain.

Need help?

Can't find what you're looking for? Contact our support team for a quick reply.

Contact Support