Skip to main content
Ayakaleaf Pro comes with the option to run compiles in a secured sandbox environment for enterprise security. It does this by running every project in its own secured docker environment.

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.
If you attempt to run Ayakaleaf Pro without Sandboxed Compiles, the compile runs alongside other concurrent compiles inside the main Docker container and users have full read and write access to the sharelatex container resources (filesystem, network and environment variables) when running LaTeX compiles.

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.
As Ayakaleaf Pro has been architected to work offline, there isn’t an automated way to integrate overleaf.com gallery templates into your on-premise installation; it is, however, possible to do this manually on a per-template basis. For more information on how this works, please check out our transferring templates from overleaf.com guide: #transferring-templates-from-overleaf.com.
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 the sharelatex 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 texlive container for the compile run.
  • Have the texlive container read the project data from the location under OVERLEAF_DATA_PATH.
  • Compile the project inside the texlive container.

Enabling Sandboxed Compiles

For Toolkit User

To enable sandboxed compiles (also known as Sibling containers), set the following configuration options in overleaf-toolkit/config/overleaf.rc:
config/overleaf.rc
To disable them, set 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 ghcr.nju.edu.cn mirror to speed up the download, then tag them with their ghcr.io name:
DO NOT use 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.
Ayakaleaf Pro uses three environment variables to determine which TeX Live images to use for Sandboxed Compiles:
  • TEX_LIVE_DOCKER_IMAGE (optional), The TeX Live image used by new projects. It must be one of the images in ALL_TEX_LIVE_DOCKER_IMAGES. If unset, new projects use the first image in ALL_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 example 2026.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, set SIBLING_CONTAINERS_PULL=false in config/overleaf.rc.
When starting your Ayakaleaf Pro instance using the 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.
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 to TEX_LIVE_DOCKER_IMAGE and ALL_TEX_LIVE_DOCKER_IMAGES:
  • ghcr.io/ayaka-notes/texlive-full:2026.1 (Also latest tag)
  • ghcr.io/ayaka-notes/texlive-full:2025.1
  • ghcr.io/ayaka-notes/texlive-full:2024.1
  • ghcr.io/ayaka-notes/texlive-full:2023.1
  • ghcr.io/ayaka-notes/texlive-full:2022.1
  • ghcr.io/ayaka-notes/texlive-full:2021.1
  • ghcr.io/ayaka-notes/texlive-full:2020.1
There is a strict schema concerning how images must be tagged (the following regex applies ^[0-9]+.[0-9]+, for which the first number determines the TeX Live year and the second the patch version).

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
Then, you need to make sure, all the images of texlive are in your-repo, like
  • hub.your.com/your-repo/texlive-full:2025.1
  • hub.your.com/your-repo/texlive-full:2024.1
For detailed infomation, read the source code below to understand how we parse your env var:
sandboxed-compiles/index.mjs

Automated TeX Live Image Sync

To avoid manual updates with bin/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:
Using 6.0.1-ext-v3.3, I have these settings in variables.env:
This works fine with texlive/texlive:latest-full. However, i pulled another texlive image danteev/texlive:2025-10-15 and 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 in variables.env are not taking effect. Compile still tries to run the texlive/texlive:latest-full image, not the new image. I tried rebooting, deleting the containers and re-run, but still the same issue. Any solutions?
Due to some technical limitations, if you only set up a single Docker TeXLive image, such as texlive-fullA:latest
And after running your overleaf instance for a while, you might want to modify the TeXLive image to texlive-fullB:latest. Then, you will see that your users are unable to compile all projects.
This is because the name of TeXLive-Full image (for sandbox compile) in each project is persisted in the database. Only when user switch his project’s TeXLive verion, for example, from 2024 to 2025, will the image name be changed in database. When CLSI compiles a project, it uses the container image name found in the database to directly compile the project. If you only provide one Docker image, users will not be able to modify the image used to compile the project. In this case, you need to write a script to manually modify the TeXLive image for all user projects in mongoDB.

Debug and Report

Run the following command to check clsi log from toolkit:
If you encounter any issues compiling with the TeX Live images, please submit an issue here: https://github.com/ayaka-notes/texlive-full/issues/new?template=texlive-image-bug.yml To help us reproduce and troubleshoot the problem, you may be asked to upload your project to Overleaf. We will then pull the project and run compilation tests with GitHub Action.

Q&A

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/compiles and output) 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 with docker image rm <image>.
There is no need to delete these containers by hand.
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.
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.
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.
Last modified on November 8, 2026