feat: add ARM64 support for AgentENV by zlzGithub-0801 · Pull Request #86 · kvcache-ai/AgentENV

zlzGithub-0801 · 2026-07-30T07:44:13Z

What

Add ARM64/aarch64 support across AgentENV runtime dependency provisioning, release artifacts, and Docker images.

Why

AgentENV installation and Server releases previously assumed x86_64. On ARM64 hosts, the installer rejected the architecture and dependency setup could not resolve an architecture-specific kernel artifact.

Related issue

Closes #60, #63

Scope and non-goals

Included:

Firecracker and Linux kernel download paths
Release behavior
Installation script

Not included:

Other AgentENV runtime logic

Design and behavior changes

During setup, download the matching Firecracker binary and Linux kernel based on the configured version and host architecture.
Add aenv-server-linux-aarch64.tar.gz to the release artifacts and publish the Docker image as a multi-architecture image.
Update the installation script to select the appropriate release artifact based on the host architecture.

Compatibility and operations

Public API or generated protocol: N/A — no API schema or generated code changes.
Configuration or defaults: The bundled Firecracker and kernel URLs now point to the kvcache-ai/firecracker GitHub Release and include architecture-specific asset names.
Snapshot manifest, artifact layout, or storage format: N/A — no snapshot or persistent storage format changes.
Upgrade and rollback: N/A — Existing x86_64 installations remain supported.
Host requirements, permissions, ports, or dependencies: ARM64 execution requires an aarch64 Linux host with KVM access and the same existing AgentENV host requirements.

Validation

make fmt
make clippy
make test-unit
Relevant Rust integration tests
make -C services test (required when services/ changes)
Generated clients/server regenerated with the documented make target
Documentation updated
Benchmarks or performance comparison completed

Commands and results:

Skipped checks and reasons:

This PR does not change services/ and doesn't have performance-sensitive change either.

Risks and reviewer notes

Checklist

The PR contains one coherent change and no unrelated formatting or refactoring.
New behavior is covered by tests, or I explained why testing is impractical.
Logs and examples contain no credentials, tokens, or private registry information.
I did not manually edit generated code without updating its source and regenerating it.

github-actions · 2026-07-30T08:05:07Z

🔍 OpenCodeReview found 2 issue(s) in this PR.

✅ Successfully posted inline: 1 comment(s)
❌ Failed to post inline: 1 comment(s)

[security · high]

📄 `.github/workflows/release.yml` (L198-L202)

⚠️ GitHub could not post this as an inline comment: Unprocessable Entity: "Line could not be resolved" - https://docs.github.com/rest/pulls/reviews#create-a-review-for-a-pull-request

These newly added third-party actions run in a job with packages: write, but mutable major-version tags are used. If either tag is moved or compromised, the action can access the job token and modify published packages. Pin both actions to reviewed full commit SHAs (and keep the version comments for upgrade tracking).

💡 Suggested Change

Before:

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Log in to GHCR
        uses: docker/login-action@v4

After:

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@<full-reviewed-commit-sha> # v4

      - name: Log in to GHCR
        uses: docker/login-action@<full-reviewed-commit-sha> # v4

github-actions · 2026-07-30T08:05:08Z

+        run: echo "OWNER=${GITHUB_REPOSITORY_OWNER,,}" >> "$GITHUB_ENV"

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4


[security · high]
This newly added publishing job runs Docker-maintained third-party actions by mutable tags while holding packages: write; the following login action also receives GITHUB_TOKEN. If either tag is retargeted or compromised, its code can steal the token or publish a tampered manifest. Pin both docker/setup-buildx-action and docker/login-action in this job to audited full commit SHAs.

github-actions · 2026-07-30T08:05:08Z

+  docker-publish:
+    name: Publish multi-architecture Docker image
+    needs: docker-build
+    runs-on: ubuntu-24.04


[other · medium]
This new registry-publishing job has no timeout-minutes. A stalled Buildx setup, registry manifest operation, or inspection can occupy the runner and leave the release workflow blocked until the platform limit. Add a bounded timeout appropriate for registry operations (for example, 30 minutes).

Suggestion:

Suggested change

docker-publish:

name: Publish multi-architecture Docker image

needs: docker-build

runs-on: ubuntu-24.04

docker-publish:

name: Publish multi-architecture Docker image

needs: docker-build

runs-on: ubuntu-24.04

timeout-minutes: 30

YXalix · 2026-07-30T08:19:12Z

Where could I build vmlinux myself

yingdi-shan · 2026-07-30T10:07:10Z

Where could I build vmlinux myself

This is just a Linux kernel built from Firecracker's microvm-kernel-ci-aarch64-6.1.config. You can build your own kernel using this config and enable additional options as needed.

github-actions · 2026-07-30T12:20:05Z

+    name: e2e-tests (${{ matrix.e2e_name }}, ${{ matrix.os }})
    # Ubuntu 24.04's Linux 6.17 kernel can crash in ublk ADD_DEV.
-    runs-on: ubuntu-22.04
+    runs-on: ${{ matrix.os }}


[other · medium]
This expanded matrix has no timeout-minutes, so any hung KVM/ublk or compose test can occupy both x64 and ARM runners indefinitely. Add a job-level timeout sized for the slowest ARM leg to bound resource consumption.

Suggestion:

Suggested change

runs-on: ${{ matrix.os }}

runs-on: ${{ matrix.os }}

timeout-minutes: 60

github-actions · 2026-07-30T12:20:08Z

+        os:
+          - ubuntu-22.04
+          - ubuntu-22.04-arm


[performance · medium]
The new architecture legs share the same BuildKit GHA cache scopes (agentenv-runtime, agentenv-gateway, and agentenv-scheduler). Because both OS legs can export those scopes concurrently on main, the last writer can replace the other architecture's cache, causing persistent misses or cache thrashing. Include the architecture/OS in each cache-from and cache-to scope (for example, ${{ runner.arch }}), as the release workflow does.

github-actions · 2026-07-30T12:20:13Z

+  docker-publish:
+    name: Publish multi-architecture Docker image
+    needs: docker-build
+    runs-on: ubuntu-24.04


[other · medium]
Add timeout-minutes to this new publication job. Registry login, manifest creation, or inspection can otherwise stall until GitHub's much longer default job limit, leaving a release run and runner occupied. A timeout consistent with the adjacent Docker build job (for example, 30 minutes) would bound this failure mode.

Suggestion:

Suggested change

docker-publish:

name: Publish multi-architecture Docker image

needs: docker-build

runs-on: ubuntu-24.04

docker-publish:

name: Publish multi-architecture Docker image

needs: docker-build

runs-on: ubuntu-24.04

timeout-minutes: 30

github-actions · 2026-07-30T12:20:16Z

+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Set lowercase owner


[security · low]
This manifest-only job does not check out or otherwise read repository contents, so contents: read is unnecessary. Set contents: none (or omit it, since declaring job permissions makes unspecified scopes none) to reduce the token privileges exposed to the publishing steps.

Suggestion:

Suggested change

permissions:

contents: read

packages: write

steps:

- name: Set lowercase owner

permissions:

packages: write

steps:

- name: Set lowercase owner

github-actions · 2026-07-30T14:34:59Z

+            --tag "${image}:${version}" \
+            --tag "${image}:latest" \


[bug · low]
Every tag-triggered workflow unconditionally rewrites the shared latest tag, and this workflow has no concurrency or version-order guard. Overlapping or retried releases can therefore let an older release finish last and point latest backward. Serialize publication and/or update latest only after verifying this tag is the newest release; alternatively publish only the immutable version tag.

Suggestion:

Suggested change

--tag "${image}:${version}" \

--tag "${image}:latest" \

--tag "${image}:${version}" \

github-actions Bot reviewed Jul 30, 2026

View reviewed changes

zlzGithub-0801 closed this Jul 30, 2026

zlzGithub-0801 reopened this Jul 30, 2026

zlzGithub-0801 force-pushed the feat/arm64-support branch 3 times, most recently from cfa3d2c to ba9871d Compare July 30, 2026 11:25

LSX-s-Software requested changes Jul 30, 2026

View reviewed changes

Comment thread .github/workflows/integration-tests.yml Outdated

Comment thread .github/workflows/release.yml Outdated

github-actions Bot reviewed Jul 30, 2026

View reviewed changes

zlzGithub-0801 force-pushed the feat/arm64-support branch 2 times, most recently from f350b27 to b042bc8 Compare July 30, 2026 13:44

feat: add ARM64 support for AgentENV

9903e36

zlzGithub-0801 force-pushed the feat/arm64-support branch from b042bc8 to 9903e36 Compare July 30, 2026 13:46

github-actions Bot reviewed Jul 30, 2026

View reviewed changes

liunianxuxie mentioned this pull request Jul 31, 2026

feat: add ARM (aarch64) platform support #94

Open

leether mentioned this pull request Jul 31, 2026

[RFC] Exploring an end-to-end ARM64 support path for AgentENV: findings from a validated DGX Spark deployment #101

Open

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add ARM64 support for AgentENV - #86

feat: add ARM64 support for AgentENV#86
zlzGithub-0801 wants to merge 1 commit into
kvcache-ai:mainfrom
zlzGithub-0801:feat/arm64-support

zlzGithub-0801 commented Jul 30, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 30, 2026 •

edited

Loading

Uh oh!

github-actions Bot Jul 30, 2026

Uh oh!

github-actions Bot Jul 30, 2026

Uh oh!

YXalix commented Jul 30, 2026

Uh oh!

yingdi-shan commented Jul 30, 2026

Uh oh!

Uh oh!

Uh oh!

github-actions Bot Jul 30, 2026

Uh oh!

github-actions Bot Jul 30, 2026

Uh oh!

github-actions Bot Jul 30, 2026

Uh oh!

github-actions Bot Jul 30, 2026

Uh oh!

github-actions Bot Jul 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	runs-on: ${{ matrix.os }}
	runs-on: ${{ matrix.os }}
	timeout-minutes: 60

	--tag "${image}:${version}" \
	--tag "${image}:latest" \
	--tag "${image}:${version}" \

Uh oh!

Conversation

zlzGithub-0801 commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

Related issue

Scope and non-goals

Design and behavior changes

Compatibility and operations

Validation

Risks and reviewer notes

Checklist

Uh oh!

github-actions Bot commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📄 .github/workflows/release.yml (L198-L202)

Uh oh!

github-actions Bot Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

YXalix commented Jul 30, 2026

Uh oh!

yingdi-shan commented Jul 30, 2026

Uh oh!

Uh oh!

Uh oh!

github-actions Bot Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

zlzGithub-0801 commented Jul 30, 2026 •

edited

Loading

github-actions Bot commented Jul 30, 2026 •

edited

Loading

📄 `.github/workflows/release.yml` (L198-L202)