topo

Topo CLI

Discover what your Arm hardware can do and deploy workloads that use it to its full potential.

Every Arm system has a different mix of architecture features, and many include additional specialized processors alongside the main CPU. Topo connects to your target over SSH, probes its capabilities, and matches it to ready-made containerized workloads that fully leverage your specific hardware. Where a system has multiple processors, Topo can install companion runtimes like remoteproc-runtime to extend container workloads across all of them.

Core Concepts

Host and Target

Topo operates across two machines:

• Host machine — your laptop, workstation, or CI runner where you run the topo CLI. It connects to the target over SSH and builds container images locally.
• Target machine — a remote Arm Linux system (e.g. Raspberry Pi, custom SoC, cloud Graviton instance) reachable over SSH. Topo deploys and runs containerized workloads on this machine.

Commands that connect to the target accept a --target flag with an SSH destination (user@host or an SSH config alias). Set TOPO_TARGET once in your environment to skip repeating it:

export TOPO_TARGET=user@my-board

If host and target are the same system, use --target localhost.

Target Description

The topo describe command probes your board and writes a target-description.yaml that captures CPU features, core topology, and any heterogeneous processors.

Templates

Topo templates extend the Compose Specification popularised by Docker, adding x-topo metadata that declares CPU feature requirements and build arguments. Topo uses your target description to match and configure compatible templates for your board. Templates can come from the built-in catalog (template:Name), a git repository (git:https://...), or a local directory (dir:path).

The full format specification is at arm/topo-template-format.

Installation

Download the latest binary for your platform from GitHub Releases, extract it, and place it on your PATH.

To build from source instead (requires Go 1.26+):

go build ./cmd/topo

Prerequisites

Host machine (where you run topo):

• SSH client (ssh)
• Docker

Target machine (the remote Arm system):

• Linux on ARM64
• Docker
• lscpu (typically pre-installed; used for hardware probing)
• SSH server

The host and target can be the same system. If you're working directly on an Arm Linux system, use --target localhost.

Getting Started

This walkthrough takes you from first connection to a running deployment. The examples use my-board as the SSH destination — replace it with your own user@host or SSH config alias, or set TOPO_TARGET once to skip repeating it:

export TOPO_TARGET=user@my-board

1. Check that everything is ready

topo health --target my-board

Host
----
SSH: ✅ (ssh)
Container Engine: ✅ (docker)

Target
------
Connectivity: ✅
Container Engine: ✅ (docker)
Hardware Info: ✅ (lscpu)
Subsystem Driver (remoteproc): ⚠️ (no remoteproc devices found)

Resolve any ❌ before continuing. A ⚠️ is informational and won't block the core workflow.

2. Describe your target hardware

topo describe --target my-board

This SSHs into the target, probes CPU features, and writes a target-description.yaml in the current directory. Topo uses this file to match your system to compatible templates.

3. Find a template

topo templates --target-description target-description.yaml

This lists available templates and indicates compatibility with your target hardware. If you don't already have a target description file for your board, you can still use:

topo templates --target my-board

4. Clone a template into a new project

topo clone template:topo-welcome

If the template requires build arguments, Topo will prompt you for them. You can also supply them on the command line:

topo clone template:topo-welcome GREETING_NAME="World"

This creates a project directory containing a compose.yaml, and any source files from the template.

5. Deploy to your target

cd my-project/
topo deploy --target my-board

Topo builds the container images on your host, transfers them to the target over SSH, and starts the services.

6. Stop the deployment

When you're done, stop the running services:

topo stop --target my-board

Other Commands

The Getting Started walkthrough above covers the core flow. These additional commands are available:

Run topo <command> --help for full usage details.