Deploy containerized workloads to Arm-based Linux targets with Topo
Introduction
Install Topo on your host machine
Use Topo to assess target compatibility
Deploy a compatible containerized workload with Topo
(Optional) Use the Topo VS Code extension
Next Steps

  Log an issue

  Fork and edit

  Discuss on Discord

About this Learning Path

Skill level:  Introductory
Reading time:  30 min
Last updated:  29 Jul 2026
Skill level:
  Introductory
Reading time:
  30 min
Last updated:
  29 Jul 2026
Author:Matt Cossins, Arm
Arm IP:Neoverse Cortex-A Cortex-M
Tags: Containers and Virtualization Linux macOS Windows Topo Docker SSH Visual Studio Code
Author:
  • Matt Cossins, Arm
Arm IP:
Neoverse Cortex-A Cortex-M
Tags:
Containers and Virtualization Linux macOS Windows Topo Docker SSH Visual Studio Code

Who is this for?

This is an introductory topic for embedded, edge, and cloud software developers who want to deploy containerized workloads to Arm-based Linux targets using Topo.

What will you learn?

Upon completion of this Learning Path, you will be able to:

  • Install Topo and verify that the host and target environments are ready for deployment
  • Run health checks and list compatible projects for your target
  • Clone a Topo Project and deploy a containerized workload to an Arm-based Linux target
  • (Optional) Use the Topo VS Code extension to run the same target, project, and deployment workflow from Visual Studio Code
  • (Optional) Deploy firmware and applications to heterogeneous Cortex-A + Cortex-M devices using remoteproc-runtime

Prerequisites

Before starting, you will need the following:

  • A host machine (x86 or Arm) with Linux, macOS, or Windows
  • An Arm-based Linux target accessible over SSH, for example an Arm-based Linux VM, Raspberry Pi, DGX Spark, or NXP i.MX 93
  • Docker installed on the host and target. For installation steps, see Install Docker .
  • lscpu installed on the target (pre-installed on most Linux distributions)
  • (Optional) Visual Studio Code installed if you want to use the Topo VS Code extension.
  • Basic familiarity with containers and CLI tools

Summary

AI-assisted

This summary was drafted with an approved AI-assisted workflow and reviewed by Arm contributors before publication. Human technical review remains part of the process so the final page reflects engineering rigor, accuracy, and Arm editorial standards.

Close
?
You’ll use Topo to deploy containerized workloads to Arm-based Linux targets over SSH. You’ll install Topo on a host machine, run a health check to validate host and target readiness, and list projects compatible with the target’s Arm CPU features and hardware capabilities. You’ll then clone a starter project using an LLM chat example and deploy. Topo builds the container image on the host, transfers it to the target, and starts the services on the target; it can also build directly on the target. You’ll also see how to run the same workflow using the Topo Visual Studio Code extension.

Frequently asked questions

AI-assisted

These FAQs were drafted with an approved AI-assisted workflow and reviewed by Arm contributors before publication. Human technical review remains part of the process so the final page reflects engineering rigor, accuracy, and Arm editorial standards.

Close
?
How do I verify that my host and target are ready before deploying?
Run topo health on the host to confirm Topo, SSH, and the container engine are available. To include the target in the check, provide --target or set the TOPO_TARGET environment variable.
How do I tell Topo which target to use for health checks and deployment?
Pass --target to the Topo command or set TOPO_TARGET in your environment. The health check output prompts you when a target is not specified.
How does Topo determine if a project is compatible with my Arm target?
Topo detects hardware capabilities on the target, including Arm CPU features such as Neon and SVE, and uses them to identify compatible projects when you run topo projects --target.
What should I expect when cloning the example project and responding to prompts?
Clone the LLM chat project with topo clone. The default configuration uses the unsloth/SmolLM2-135M-Instruct-GGUF model and can be deployed immediately.
Where are images built and what happens after deployment starts?
Topo builds container images on the host, transfers them to the target over SSH, and starts the services on the target. It can also build and deploy directly on the target if you choose that workflow.
Next