ARM64 and x86_64

Aivory's application image, sandbox sidecar, and sandbox runtime images provide multi-architecture variants under the same release tag:

System command output	Docker platform	Supported
x86_64	linux/amd64	Yes
aarch64, arm64	linux/arm64	Yes
32-bit ARM such as armv7l	Non-64-bit ARM	No

Confirm the host architecture:

uname -m

Docker Compose automatically selects the matching image based on the host. The official Compose neither needs nor recommends adding platform: to force an architecture; forcing the wrong platform causes pull failures or dependence on emulation, increasing performance and stability risks.

Deploying on a new server

ARM64 and x86_64 use exactly the same deployment process: choose the Personal edition or the Full edition, create the corresponding env file, run config --images first, then pull and up -d. Do not change image names, data paths, database configuration, or sandbox addresses just for ARM64.

Before starting, still confirm that the OS is 64-bit Linux, Docker is updated to a version that supports the target architecture, and the server can reach the image registry. The application, sandbox sidecar, and runtime images should all use the same IMAGE_TAG.

Updating an existing x86_64 instance

Same-architecture updates require no migration. Keep the existing env file, Compose file, named volumes, and data directory; follow Upgrade, Backup, and Restore to pin the version and run pull and up -d --no-build.

After upgrading, check the application health endpoint, administrator login, normal conversations, files, knowledge bases, and the enabled sandbox; do not skip business acceptance just because you switched image architectures.

Migrating from x86_64 to ARM64, or the other way around

Cross-architecture migration should use "back up and restore", not sharing live volumes. Database files, container layers, and some local volume formats must not be treated as safe to mount simultaneously or copy directly to another working server.

Recommended process:

1. Complete a full backup on the old server, and separately keep copies of all persistent data.
2. Install Docker on the new-architecture server and start an empty instance with the same or a compatible Aivory version.
3. Confirm the new instance's /api/health is healthy and that the images automatically selected the correct architecture.
4. During a maintenance window, stop writes on the old instance and create a final incremental or last full backup.
5. Restore the backup into the new instance, recovering the data directory and all related data services according to the deployment mode.
6. Verify administrator login, normal conversations, attachments, knowledge base retrieval, vectors, workspaces, and needed Python capabilities.
7. Confirm that real user traffic works normally after the DNS/reverse proxy switch, then keep the old instance for a rollback window.

The Personal edition must migrate the entire DATA_DIR, not just the SQLite file; the Full edition must migrate PostgreSQL, Qdrant, Redis, the sandbox archive volume, and DATA_DIR together, or restore via a full backup from the admin backend. For the detailed scope, see Upgrade, Backup, and Restore.

Architecture-related failures

When image pulls fail, confirm each of the following in order:

• Whether uname -m reports a supported 64-bit architecture.
• Whether IMAGE_TAG is a fully released tag, rather than a version that is unreleased or has only some images.
• Whether a third-party image proxy served an incomplete or inconsistent manifest.
• Whether Docker was explicitly given the wrong platform.
• When using the local sandbox, whether all three Aivory images resolve from the same registry and the same version tag.

Do not use QEMU emulation as a long-term production solution. It is fine for temporary verification, but it makes performance and problem diagnosis for the Python sandbox, the database, and long-running document processing much harder.