Improved security
Sandboxed Compiles are the recommended approach for Ayakaleaf Pro due to many LaTeX documents requiring/having the ability to execute arbitrary shell commands as part of the PDF compile process. If you use Sandboxed Compiles, each compile runs in a separate Docker container with limited capabilities that are not shared with any other user or project and has no access to outside resources such as the host network.Easier package management
To avoid manually installing packages, we recommend enabling Sandboxed Compiles. This is a configurable setting within Ayakaleaf Pro that will provide your users with access to the same TeX Live environment as that on overleaf.com but within your own on-premise installation. TeX Live images used by Sandboxed Compiles contain the most popular packages and fonts tested against our gallery templates, ensuring maximum compatibility with on-premise projects. Enabling Sandboxed Compiles allows you to configure which TeX Live versions users are able to choose from within their project along with setting a default TeX Live image version for new projects.If you attempt to run Ayakaleaf Pro without Sandboxed Compiles, your instance will default to using a basic scheme version of TeX Live for compiles. This basic version is lightweight and only contains a very limited subset of LaTeX packages, which will most likely result in missing package errors for your users, especially if they try to use pre-built templates.
Sandboxed Compiles requires that the
sharelatex container has access to the Docker socket on the host machine (via a bind mount) so it can manage these sibling compile containers.How it works
When Sandboxed Compiles are enabled, the Docker socket will be mounted from the host machine into thesharelatex container, so that the compiler service in the container can create new Docker containers on the host. Then for each run of the compiler in each project, the LaTeX compiler service (CLSI) will do the following:
- Write out the project files to a location inside the
OVERLEAF_DATA_PATH. - Use the mounted Docker socket to create a new
texlivecontainer for the compile run. - Have the
texlivecontainer read the project data from the location underOVERLEAF_DATA_PATH. - Compile the project inside the
texlivecontainer.
Enabling Sandboxed Compiles
For Toolkit User
To enable sandboxed compiles (also known as Sibling containers), set the following configuration options inoverleaf-toolkit/config/overleaf.rc:
config/overleaf.rc
SIBLING_CONTAINERS_ENABLED=false and run bin/up. Compiles then run inside the sharelatex container with its basic TeX Live.
For Docker Compose User
Setup the TexLive Image
For China mainland users, you can pull the images from the DO NOT use
ghcr.nju.edu.cn mirror to speed up the download, then tag them with their ghcr.io name:ghcr.nju.edu.cn in your toolkit env settings: keep the ghcr.io names there. To stop bin/up from pulling the images from ghcr.io again, set SIBLING_CONTAINERS_PULL=false in config/overleaf.rc. To keep the images up to date through the mirror, see Updating TeX Live Full Images Automatically.TEX_LIVE_DOCKER_IMAGE(optional), The TeX Live image used by new projects. It must be one of the images inALL_TEX_LIVE_DOCKER_IMAGES. If unset, new projects use the first image inALL_TEX_LIVE_DOCKER_IMAGES.ALL_TEX_LIVE_DOCKER_IMAGE_NAMES(optional), A comma-separated list of names for the images, in the same order, shown in the compiler settings. If unset, or shorter than the image list, an image is shown by its tag, for example2026.1.ALL_TEX_LIVE_DOCKER_IMAGES(required), A comma-separated list of TeX Live images to use. If the Overleaf Toolkit is used for deployment, these images will be downloaded or updated. To skip downloading, setSIBLING_CONTAINERS_PULL=falseinconfig/overleaf.rc.
bin/up command, the Toolkit will automatically pull all of the images listed in ALL_TEX_LIVE_DOCKER_IMAGES.
Here’s an example where we default to TeX Live 2026 for new projects, and keep 2025 in use for old projects.
- Minium installation
- Full installation
The following configuration installs all full TeX Live Docker images from 2025 to 2026. We recommend having at least 64 GB of available storage before using this configuration.
config/variables.env
It’s highly recommended to set at least 2 texlive-full images. For detailed reason, see #known-issues
Available TeX Live images
These are a series of TeX Live images that are specially optimized for Overleaf, also can be added toTEX_LIVE_DOCKER_IMAGE and ALL_TEX_LIVE_DOCKER_IMAGES:
ghcr.io/ayaka-notes/texlive-full:2026.1(Alsolatesttag)ghcr.io/ayaka-notes/texlive-full:2025.1ghcr.io/ayaka-notes/texlive-full:2024.1ghcr.io/ayaka-notes/texlive-full:2023.1ghcr.io/ayaka-notes/texlive-full:2022.1ghcr.io/ayaka-notes/texlive-full:2021.1ghcr.io/ayaka-notes/texlive-full:2020.1
Can I Using Other Image Registry
Some people may wonder if I can replace ghcr.io with another mirror site, or switch texlive to other image from docker hub?
No, we don’t recommend it because the configuration is relatively complicated. If you are downloading from a mirror site, you can rename your image to ghcr.io/ayaka-notes/texlive-full.
But, if you really want to use your own Image Registry, please add:
config/variables.env
your-repo, like
hub.your.com/your-repo/texlive-full:2025.1hub.your.com/your-repo/texlive-full:2024.1
sandboxed-compiles/index.mjs
Automated TeX Live Image Sync
To avoid manual updates withbin/up your instance everytime, you can automate updates to your TeX Live image. See updating-tex-live-full-images-automatically.md.
Known Issues
This is a real case from overleaf community:Using6.0.1-ext-v3.3, I have these settings invariables.env:This works fine withtexlive/texlive:latest-full. However, i pulled another texlive imagedanteev/texlive:2025-10-15and changed both of these variables to the new image name but it doesn’t work:In the logs, i see the following:
It seems that the updated settings inDue to some technical limitations, if you only set up a single Docker TeXLive image, such asvariables.envare not taking effect. Compile still tries to run thetexlive/texlive:latest-fullimage, not the new image. I tried rebooting, deleting the containers and re-run, but still the same issue. Any solutions?
texlive-fullA:latest
texlive-fullB:latest. Then, you will see that your users are unable to compile all projects.
Debug and Report
Run the following command to check clsi log from toolkit:Q&A
Are the sandbox containers, compile files and TeX Live images removed automatically?
Are the sandbox containers, compile files and TeX Live images removed automatically?
Answer: The containers and compile files are, after a delay; the TeX Live images are not.
- Compile containers (
project-<project id>-<hash>) are reused across compiles of the same project, so they stay after a compile. A check runs every hour and removes the ones that are older than one hour and whose project has not been compiled in the last hour. A container is usually gone one to two hours after the last compile. Restarting Overleaf does not remove them; the next hourly check does. - Word count, SyncTeX and conversion containers are removed as soon as they finish.
- Compile files (
data/overleaf/data/compilesandoutput) are removed once a project has not been used for one day, checked every 10 minutes. When the disk runs low, this period is shortened step by step, down to half a day. - TeX Live images are never removed, since every compile needs them. To free space after removing an image from
ALL_TEX_LIVE_DOCKER_IMAGES, delete it withdocker image rm <image>.
Can a project read files from a host or NAS directory?
Can a project read files from a host or NAS directory?
Answer: No. Each compile container mounts only the compile directory of its own project, at
/compile, and has no network, and there is no setting to mount other host directories into it. Upload the files the project needs to the project instead.Is there a TeX Live basic image, and how do I configure it?
Is there a TeX Live basic image, and how do I configure it?
Answer: Yes.
ghcr.io/ayaka-notes/texlive-basic:<year>.1 (2020.1 to 2026.1) has the TeX Live basic scheme plus a few packages such as latexmk, xetex and fontspec, without the full font set. It is much smaller than texlive-full, but projects that use other packages get missing package errors. For TeX Live 2025 basic:config/variables.env
ghcr.io/ayaka-notes/texlive-full:base is not a basic image: it has no TeX Live and cannot compile.Where can I see how long a compile took?
Where can I see how long a compile took?
Answer: The editor does not show it, and the
clsi log records it only at debug level. Every compile request returns it, though: open the browser’s developer tools, go to the Network tab, recompile, and select the compile request. Its JSON response has timings in milliseconds, where compileE2E is the whole compile in the compile service and compile is the LaTeX run itself.
