Interpreter file isolation#

Interpreter file protection limits Python code to the current Chat's files, temporary data, and required libraries. A server administrator with access to Docker and the installation directory configures the protection.

Preparing the server#

The protected interpreter requires Linux with Landlock ABI 1 or later enabled. The policy is applied before code runs and is inherited by child processes. If the kernel, architecture, or Docker policy does not support the restriction, Python code is not executed.

On kernels with Landlock ABI 1 or 2, the container configuration is also checked before code runs. The process must run with UID 1000 and all Linux capabilities dropped. The container root filesystem and the bootstrap script /opt/main.py must be mounted read-only. Additional writable mounts outside the standard Docker configuration are not permitted. The supplied Docker launch configuration sets these restrictions. If a check fails, code is not executed. There is no fallback to execution without isolation.

The aiserver image, aiserver-code-interpreter image, and docker-compose.yml must be updated together from the same distribution package. The mypy image must contain the required libraries. See the image preparation instructions.

Configuring the service token#

Backend communication with the interpreter requires an AI_INTERPRETER_SERVICE_TOKEN of at least 32 characters. The installer and update script generate a random token in .env, preserve an existing value, and set file permissions to 600. An existing short value causes configuration to fail.

For manual installation, generate a token:

python3 -c 'import secrets; print(secrets.token_hex(32))'

Save the result as the value of AI_INTERPRETER_SERVICE_TOKEN in .env. The same value must be supplied to both aiserver and aiserver-code-interpreter. Do not send the token to a Chat or include it in diagnostic logs.

After loading the matching image package and configuring .env, recreate both services during an agreed maintenance window:

docker compose up -d --no-deps --force-recreate aiserver aiserver-code-interpreter

The backend is temporarily unavailable during recreation. Restarting an old container alone does not apply new images and parameters. Port 3001 is not published on the host. Requests reach the interpreter through the backend.

Working with Chat files#

In a Chat, Python accesses files in /sandbox. Files persist between requests in the same Chat. Another Chat receives a separate directory.

In interpreter mode, attached files and the contents of Assistant folders, including subfolders, are transferred to the current Chat's directory. By default, up to 40 files are processed per request. LLM_MAX_ATTACHMENT_FILES sets the limit. Files missing from disk are skipped. A new file with the same name replaces the previous file. In Agent mode, a separate tool transfers the selected file.

Upload and download support regular files up to 100 MiB and Russian filenames. Symbolic links, special files, and paths outside the Chat directory are not served. Save results directly in /sandbox with a filename that does not contain nested directories.

To verify operation, upload a small CSV in interpreter mode and request a sum calculation and an XLSX result. The result must be downloadable. Another request in the same Chat must see the CSV. A new Chat without the upload must not see it.

Restrictions and recovery#

Listing /etc, /opt, and /home, and reading /etc/passwd or service scripts are prohibited. Required library and font directories and selected utilities are allowed for imports. Allowed libraries remain accessible to code. Their inventory and individual file metadata are not secret. Do not place tokens, passwords, or application configuration in the mypy image.

If Sandbox requires enabled Landlock ABI 1 or newer appears, the administrator must check kernel Landlock support and whether Docker permits its system calls. If support is absent, update the environment. If the container configuration check fails on ABI 1 or 2, restore the restrictions in the supplied Docker configuration.

For an authentication error, check that both services receive the same token and recreate them after changing .env. If a library requires an additional system resource, provide the administrator with its name and the error message without file contents or secrets.