> ## Documentation Index
> Fetch the complete documentation index at: https://docs.varios-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update from 2026.08 to 2026.10

> Step-by-step guide for updating an on-premise installation from 2026.08.x to 2026.10 with the local code interpreter and the virtual file system

This guide walks you through updating an on-premise installation from 2026.08.x to 2026.10. With this update, the local code interpreter and the virtual file system become a permanent part of VARIOS AI, which requires manual additions to `.env` and `docker-compose.yml`. Starting with 2026.10, VARIOS AI also pulls its images from the container registry `registry.varios-ai.com` instead of `aibroker.azurecr.io`.

`<TARGETVERSION>` stands for `2026.10` or a later patch release `2026.10.x` provided by the VARIOS AI team. The examples use `/docker/variosai` as the installation directory.

## A. Beforehand (before the maintenance window)

1. Have the VARIOS AI team confirm that `<TARGETVERSION>` has been released.
2. Check disk space and memory:
   ```bash theme={null}
   df -h /var/lib/docker        # >= 10 GB free
   free -h                      # >= 1.5 GB free as sandbox reserve
   ```
3. Carry the login over to the new container registry. Your existing credentials also work for `registry.varios-ai.com`. The following command reads the login stored for `aibroker.azurecr.io` and uses it to log in to `registry.varios-ai.com`. It requires `python3`. Run it with `sudo -H`, because the update service `varios-update.service` runs as `root` and uses the login stored for `root`. If you also run `docker` as your own user without `sudo`, run the command a second time without `sudo -H`:
   ```bash theme={null}
   sudo -H python3 - <<'PY'
   import base64, json, os, subprocess
   from pathlib import Path

   old, new = "aibroker.azurecr.io", "registry.varios-ai.com"
   config_dir = Path(os.environ.get("DOCKER_CONFIG", Path.home() / ".docker"))
   cfg = json.loads((config_dir / "config.json").read_text())

   helper = cfg.get("credHelpers", {}).get(old) or cfg.get("credsStore")
   if helper:
       result = subprocess.run([f"docker-credential-{helper}", "get"], input=old, capture_output=True, text=True)
       if result.returncode != 0:
           raise SystemExit(f"No stored login found for {old}.")
       creds = json.loads(result.stdout)
       user, password = creds["Username"], creds["Secret"]
   else:
       auth = cfg.get("auths", {}).get(old, {}).get("auth")
       if not auth:
           raise SystemExit(f"No stored login found for {old}.")
       user, password = base64.b64decode(auth).decode().split(":", 1)

   if user == "<token>":
       raise SystemExit(f"Only a token is stored for {old}. Log in with username and password.")

   subprocess.run(["docker", "login", new, "--username", user, "--password-stdin"], input=password, text=True, check=True)
   PY
   ```
   The output ends with `Login Succeeded`. If the command aborts, log in directly with the credentials provided by the VARIOS AI team:
   ```bash theme={null}
   sudo docker login registry.varios-ai.com
   ```

## B. Install gVisor (optional, recommended)

1. Install `runsc` following the official guide and register it as a Docker runtime: [Installation](https://gvisor.dev/docs/user_guide/install/) and [Docker Quick Start](https://gvisor.dev/docs/user_guide/quick_start/docker/).
2. Run the Docker restart described there **only during the maintenance window**, because it restarts all containers.
3. Verify the installation:
   ```bash theme={null}
   docker info --format '{{.Runtimes}}'                      # contains runsc
   docker run --rm --runtime=runsc alpine:3 dmesg | head -3  # shows gVisor messages
   ```

## C. Backup

Create a snapshot of the virtual machine. Only continue once it exists. For more information, see [Backup and Restore](https://docs.varios-ai.com/en/monthly/operations/backup.md).

## D. Adjust `.env`

1. Check the tokens:
   ```bash theme={null}
   grep -E '^CODE_INTERPRETER_(API|WORKER)_TOKEN=' .env
   ```
2. If no line or only one line is printed, create both tokens from scratch. The first command removes a single existing line, if present:
   ```bash theme={null}
   sed -i '/^CODE_INTERPRETER_\(API\|WORKER\)_TOKEN=/d' .env
   echo "CODE_INTERPRETER_API_TOKEN=$(LC_ALL=C tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 64)"    >> .env
   echo "CODE_INTERPRETER_WORKER_TOKEN=$(LC_ALL=C tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 64)" >> .env
   ```
3. If you installed gVisor:
   ```bash theme={null}
   sed -i '/^DOCKER_RUNTIME=/d' .env
   echo "DOCKER_RUNTIME=runsc" >> .env
   ```
4. Do **not** change `VERSION=`.

## E. Adjust `docker-compose.yml`

Extend the existing `docker-compose.yml` by hand, for example with Vim (`vi docker-compose.yml`) or Nano (`nano docker-compose.yml`).

**1. Service `php` → `environment`:** insert after `MARKITDOWN_URL`

```yaml theme={null}
      CODE_INTERPRETER_URL: "http://code-interpreter:8080"
      CODE_INTERPRETER_API_TOKEN: ${CODE_INTERPRETER_API_TOKEN}
      CODE_INTERPRETER_MAX_WORKSPACE_RAW_BYTES: ${CODE_INTERPRETER_MAX_WORKSPACE_RAW_BYTES:-12582912}
      CODE_INTERPRETER_MAX_WORKSPACE_FILES: ${CODE_INTERPRETER_MAX_WORKSPACE_FILES:-20}
      CODE_INTERPRETER_MAX_OUTPUT_FILE_BYTES: ${CODE_INTERPRETER_MAX_OUTPUT_FILE_BYTES:-10485760}
      CODE_INTERPRETER_ARCHIVE_MAX_DEPTH: ${CODE_INTERPRETER_ARCHIVE_MAX_DEPTH:-8}
```

**2. Service `php` → `depends_on`:** add one line

```yaml theme={null}
      - code-interpreter
```

**3. Three new services** at the `services:` level, for example before `redis:`:

```yaml theme={null}
  code-interpreter:
    image: registry.varios-ai.com/variosai/code-interpreter-gateway:${VERSION}
    restart: always
    depends_on:
      - code-interpreter-worker
    init: true
    read_only: true
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    pids_limit: 256
    tmpfs:
      - /tmp:rw,nosuid,nodev,noexec,size=64m
    environment:
      PYTHONDONTWRITEBYTECODE: "1"
      PYTHONUNBUFFERED: "1"
      CODE_INTERPRETER_API_TOKEN: ${CODE_INTERPRETER_API_TOKEN}
      CODE_INTERPRETER_WORKER_URL: "http://code-interpreter-worker:8080"
      CODE_INTERPRETER_WORKER_TOKEN: ${CODE_INTERPRETER_WORKER_TOKEN}
      CODE_INTERPRETER_TIMEOUT_SECONDS: "60"
      CODE_INTERPRETER_MAX_REQUEST_BYTES: ${CODE_INTERPRETER_MAX_REQUEST_BYTES:-20000000}
      CODE_INTERPRETER_MAX_CODE_CHARS: ${CODE_INTERPRETER_MAX_CODE_CHARS:-200000}
      CODE_INTERPRETER_MAX_WORKSPACE_FILES: ${CODE_INTERPRETER_MAX_WORKSPACE_FILES:-20}
      CODE_INTERPRETER_MAX_WORKSPACE_FILE_B64_CHARS: ${CODE_INTERPRETER_MAX_WORKSPACE_FILE_B64_CHARS:-18000000}
    networks:
      - internal
      - code_interpreter_internal

  # Pull sandbox image and keep it on the host (idle holder) so docker system prune -a won't remove it.
  code-interpreter-sandbox-image:
    image: registry.varios-ai.com/variosai/code-interpreter-sandbox-python:${VERSION}
    command: ["sleep", "infinity"]
    restart: always

  code-interpreter-worker:
    image: registry.varios-ai.com/variosai/code-interpreter-worker:${VERSION}
    restart: always
    init: true
    read_only: true
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    pids_limit: 256
    tmpfs:
      - /tmp:rw,nosuid,nodev,noexec,size=64m
    environment:
      PYTHONDONTWRITEBYTECODE: "1"
      PYTHONUNBUFFERED: "1"
      CODE_INTERPRETER_WORKER_TOKEN: ${CODE_INTERPRETER_WORKER_TOKEN}
      VERSION: ${VERSION}
      CODE_INTERPRETER_TIMEOUT_SECONDS: "60"
      CODE_INTERPRETER_MEM_LIMIT: "512m"
      CODE_INTERPRETER_MAX_REQUEST_BYTES: ${CODE_INTERPRETER_MAX_REQUEST_BYTES:-20000000}
      CODE_INTERPRETER_MAX_CONCURRENT_EXECUTIONS: ${CODE_INTERPRETER_MAX_CONCURRENT_EXECUTIONS:-2}
      CODE_INTERPRETER_MAX_CODE_CHARS: ${CODE_INTERPRETER_MAX_CODE_CHARS:-200000}
      CODE_INTERPRETER_WORKDIR: ${CODE_INTERPRETER_WORKDIR:-/mnt}
      CODE_INTERPRETER_SANDBOX_UID: ${CODE_INTERPRETER_SANDBOX_UID:-65534}
      CODE_INTERPRETER_SANDBOX_GID: ${CODE_INTERPRETER_SANDBOX_GID:-65534}
      CODE_INTERPRETER_MAX_WORKSPACE_RAW_BYTES: ${CODE_INTERPRETER_MAX_WORKSPACE_RAW_BYTES:-12582912}
      CODE_INTERPRETER_MAX_WORKSPACE_FILES: ${CODE_INTERPRETER_MAX_WORKSPACE_FILES:-20}
      CODE_INTERPRETER_MAX_WORKSPACE_FILE_B64_CHARS: ${CODE_INTERPRETER_MAX_WORKSPACE_FILE_B64_CHARS:-18000000}
      CODE_INTERPRETER_WORKSPACE_TMPFS_MB: ${CODE_INTERPRETER_WORKSPACE_TMPFS_MB:-128}
      CODE_INTERPRETER_MAX_ARCHIVE_FILES: ${CODE_INTERPRETER_MAX_ARCHIVE_FILES:-30}
      CODE_INTERPRETER_MAX_OUTPUT_FILE_BYTES: ${CODE_INTERPRETER_MAX_OUTPUT_FILE_BYTES:-10485760}
      CODE_INTERPRETER_PIDS_LIMIT: ${CODE_INTERPRETER_PIDS_LIMIT:-128}
      CODE_INTERPRETER_NPROC_LIMIT: ${CODE_INTERPRETER_NPROC_LIMIT:-128}
      CODE_INTERPRETER_NOFILE_LIMIT: ${CODE_INTERPRETER_NOFILE_LIMIT:-1024}
      CODE_INTERPRETER_LOG_MAX_SIZE: ${CODE_INTERPRETER_LOG_MAX_SIZE:-64m}
      CODE_INTERPRETER_ARCHIVE_MAX_DEPTH: ${CODE_INTERPRETER_ARCHIVE_MAX_DEPTH:-8}
      # Sandbox runtime: unset/empty = default runc; set DOCKER_RUNTIME=runsc when gVisor is installed on the host.
      DOCKER_RUNTIME: ${DOCKER_RUNTIME:-}
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - code_interpreter_internal
```

**4. Section `networks:`** at the end of the file

```yaml theme={null}
networks:
  internal:
  code_interpreter_internal:
    internal: true
```

**5. Switch the image names to the new registry:** The following command replaces the domain `aibroker.azurecr.io` with `registry.varios-ai.com` throughout the file. Older installations also still use the path `avency/botapi/`, which becomes `variosai/`.

```bash theme={null}
sed -i \
  -e 's#aibroker\.azurecr\.io/avency/botapi/#registry.varios-ai.com/variosai/#g' \
  -e 's#aibroker\.azurecr\.io/#registry.varios-ai.com/#g' \
  docker-compose.yml
grep -n 'image:' docker-compose.yml
```

`aibroker.azurecr.io` must no longer appear in the output. The code interpreter only starts its sandbox from `registry.varios-ai.com/variosai/code-interpreter-sandbox-python`.

Check the file:

```bash theme={null}
docker compose config --quiet && echo OK
```

## F. Run the update

Choose one of the two options. [systemd Service](https://docs.varios-ai.com/en/monthly/security/systemd-service.md) describes how the update service works.

> [tab] update\_version file
>
> 1. ```bash theme={null}
>    systemctl is-active varios-update.service     # active
>    ```
> 2. ```bash theme={null}
>    echo "<TARGETVERSION>" > update_version
>    ```
> 3. Follow the progress until `Update successfully completed`:
>    ```bash theme={null}
>    journalctl -u varios-update.service -f
>    ```

> [tab] Manual
>
> ```bash theme={null}
> sudo systemctl stop varios-update.service
> sed -i "s/^VERSION=.*/VERSION=<TARGETVERSION>/" .env
> echo "<TARGETVERSION>" > update_version
> docker compose pull
> docker compose up -d
> docker compose ps
> docker compose exec php ./update.sh
> docker system prune -f -a --volumes
> sudo systemctl start varios-update.service
> ```

## G. After the update: populate the virtual file system

```bash theme={null}
cd /docker/variosai
docker compose exec -u www-data php /data/flow vfs:status
```

The output must read `No virtual filesystem containers exist yet.` **without** a red error line. Otherwise, fix the error first (section I) and then continue.

```bash theme={null}
docker compose exec -u www-data php /data/flow vfs:backfill --dry-run
docker compose exec -u www-data php /data/flow vfs:backfill
docker compose exec -u www-data php /data/flow vfs:backfillknowledgebases --dry-run
docker compose exec -u www-data php /data/flow vfs:backfillknowledgebases
docker compose exec -u www-data php /data/flow vfs:status
```

## H. Verify

1. ```bash theme={null}
   docker compose ps                                   # all running, no restart loop
   docker compose images | grep -E 'php|code-interpreter'   # all <TARGETVERSION>
   docker compose logs --tail=30 code-interpreter code-interpreter-worker
   docker compose exec php curl -s http://code-interpreter:8080/health     # {"status":"ok"}
   ```
2. In the user interface, **System information** shows `<TARGETVERSION>` and **Service Status** has no red entries.
3. If you installed gVisor: a sandbox run only takes a few seconds. Start the following command before the test chat. It waits for the next sandbox container and prints its runtime:
   ```bash theme={null}
   image=registry.varios-ai.com/variosai/code-interpreter-sandbox-python:<TARGETVERSION>
   until ids=$(docker ps -q --filter network=none --filter ancestor="$image") && [ -n "$ids" ] \
     && docker inspect --format '{{.Name}} runtime={{.HostConfig.Runtime}}' $ids 2>/dev/null; do
     sleep 0.2
   done
   ```
4. Start a test chat with the code interpreter: "Use Python to calculate the first 20 prime numbers and save them as primes.txt." The file appears in the chat and in the **Files** panel. With gVisor, the command from step 3 now prints `runtime=runsc` and exits. If the test chat fails, stop the command with `Ctrl+C`.
5. Ask an assistant with files a question whose answer can only come from its files.
6. ```bash theme={null}
   systemctl is-active varios-update.service     # active
   tail -n 20 Data/Logs/System.log               # no AVX2 warning
   ```

## I. If something fails

| Message / symptom | Action |
| - | - |
| Gateway log: `CODE_INTERPRETER_API_TOKEN must be set` / `must be at least 32 bytes` / `must not be identical` | Repeat section D, then `docker compose up -d code-interpreter code-interpreter-worker` |
| `vfs:status`: `CODE_INTERPRETER_URL is not configured` | Check section E, then `docker compose up -d php` |
| `vfs:status`: `No embedding model is configured` / `has no credential` | Create an [embedding model](https://docs.varios-ai.com/en/monthly/admin/models/embedding.md) with credentials |
| `docker compose pull` reports `unauthorized` or `denied` for `registry.varios-ai.com` | Repeat section A, step 3 with `sudo -H`; if you run `docker` without `sudo`, also repeat it without `sudo -H` |
| Worker log: `Interpreter image not available locally` | Check that `code-interpreter-sandbox-image` points to `registry.varios-ai.com/variosai/code-interpreter-sandbox-python` (section E, step 5), then `docker compose pull code-interpreter-sandbox-image && docker compose up -d code-interpreter-sandbox-image` |
| Worker log: `unknown or invalid runtime name: runsc` | Section B (registration as described in the gVisor documentation, Docker restart), then `docker compose restart code-interpreter-worker` |
| Section H, step 3 shows `runtime=runc` | Check `DOCKER_RUNTIME=runsc` in `.env` (section D) and `DOCKER_RUNTIME: ${DOCKER_RUNTIME:-}` on the `code-interpreter-worker` service (section E), then `docker compose up -d code-interpreter-worker` |
| `vfs:backfill`: `A backfill is already running` | Wait; otherwise check the lock file `Data/Data/Persistent/vfs_backfill.lock` |
| `update.sh` aborts | Read the message, fix the cause, run `docker compose exec php ./update.sh` again |
| `.env` shows the old `VERSION` again | `VERSION` was changed by hand while the update service was running → section F, option **update\_version file** or **Manual** |

> [!WARNING]
>
> **Rollback:** Restore the VM snapshot. Do not downgrade via **Change version**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.