Topo

The Topo extension makes it easy for application developers to deploy containers to Arm-based edge devices running Linux, including systems with additional remote processors such as Cortex-M or Cortex-R.

Features include:

Target management: Connect to targets over SSH, inspect target status, and check target compatibility.
Example discovery: Discover Topo Projects for your target.
Configure projects: Topo Projects are standard Docker Compose projects that you can configure for your use case.
Deployment: Build and deploy projects to your target.
Container actions: Manage individual containers within a deployment.

Who is this for?

You just got a board and want to see what it can do. Topo scans your target and finds Topo Projects that showcase its capabilities, from running an LLM to comparing SIMD performance. Each one deploys in minutes and is a real Compose project you can learn from or build on.

You want a faster edit-build-deploy loop. Build on your laptop and deploy to a Pi or Jetson over SSH. Rebuilds are incremental, so after the first deploy you're often iterating in seconds.

You have a heterogeneous device and want to use all of it. Your board has remote processors like a Cortex-M that normally need separate toolchains and manual firmware loading. Topo and Remoteproc Runtime let you orchestrate the whole device as one Docker Compose project.

Not sure what these terms mean? The glossary defines Topo's core concepts.

Requirements

Host machine (where this extension will run):

Visual Studio Code v1.101.0 or newer
Docker
OpenSSH Client
curl

Target machine (the remote Arm system):

Reachable with SSH
Linux on ARM64
Docker

The host and target can be the same system.

Getting Started

Install the extension from the VS Code Marketplace or a .vsix package.
Select a target from the Target view in the Topo activity bar container.
Review target health and apply suggested fixes.
Clone a Topo Project from our catalog.
Deploy the configured project to your target.
Expand the project in the Projects view to see deployed containers grouped by processing domain.

Target Management

The Target view appears in the Topo activity bar container and shows the currently selected target where deployments run.

Select a Target

Click Select a target in the Target view title bar or status bar to open the target picker. The picker shows saved targets and hosts from your SSH config. Select an existing target, choose an SSH config host, or type an SSH destination (for example root@192.168.1.1) to add and select a new target.

Remove a Target

Saved targets that do not come from SSH config can be removed from the picker with the inline trash button.

Target Tree

The Target view header shows the selected SSH destination. The tree below it shows:

Item	Description
Connectivity	SSH or target health connectivity errors when the selected target cannot be used.
Health	Required target components and processing-domain driver health-check issues shown for the target.
Processing Domains	Processing domains available on the target, including the Linux Host and remote processors.

If no target is selected, the view shows a Select a target button.

Target Actions

Use the buttons in the Target view title bar to access these actions:

Command	Description
Select a target	Select, add, or remove saved manual targets.
Connect via SSH	Open an SSH terminal when target connectivity is healthy.
Refresh	Re-check health for the selected target.
Clear Selection	Clear the active target without deleting it.
Fix Issues	Select and run available fixes for target health issues.

Health Actions

Use the inline Fix button on a fixable health issue to run the executable fix command reported by the Topo health check. Use Fix Issues on the Health row to select and run fixes for multiple target health issues.

Container Actions

Use the inline buttons on a service in the Projects tree to manage individual containers:

Command	Description
Start	Start a stopped container.
Stop	Stop a running container.
Delete	Remove a container.
Open Container Shell	Open a VS Code terminal connected to a running Linux Host container.
Open in Browser	Open a running container's web endpoint in your browser.

Deploy and Stop

Deploy or stop a project on the selected target. A deploy operation builds container images, transfers them to the target, and starts services. You can trigger either operation from:

Running Topo: Deploy from the Command Palette, then selecting a compose.yaml file from the workspace.
Right-clicking compose.yaml in the Explorer or editor tab and selecting Topo Deploy or Topo Stop.
Using the inline Deploy or Stop buttons on a project in the Projects view.

Project Management

The Projects view appears in the Topo activity bar container and lists workspace projects discovered from top-level compose.yaml or compose.yml files.

When a target is selected, each project can expand to show deployed containers for that project, grouped by processing domain.

Use the inline buttons on a project row to deploy or stop that project's compose file on the selected target. These actions behave the same as running Topo Deploy or Topo Stop from the context menu of the project's compose file.

Initialize a Project

Use the Topo: Initialize Project command from the Command Palette to create a new Topo project in the current workspace.

Clone a Project

Two clone commands are available from the Command Palette:

Command	Description
Topo: Clone Remote Project	Clone from a custom Git repository or a curated list of projects.
Topo: Clone Local Project	Clone from a local directory.

After cloning, the extension offers to open the project in the current window, a new window, or add it to the workspace.

Protocol Handler

The extension supports a URI scheme for cloning projects from external links:

vscode://arm.topo/clone?source=git:https://github.com/example/repo

Host Health Check

The Host view appears in the Topo activity bar container and shows host health for tools such as Docker and SSH. Missing or unhealthy health checks are shown in the tree.

Use the refresh button in the Host view title bar to reload host health.

Commands

Commands available from the Command Palette:

Command	Description
`Topo: Initialize Project`	Initialize a new Topo project in the workspace.
`Topo: Clone Remote Project`	Clone from a custom Git repository or a curated list of projects.
`Topo: Clone Local Project`	Clone a project from a local directory.
`Topo: Deploy`	Select and deploy a compose file to the target.

Additional commands are available through inline buttons in the Target, Host, and Projects tree views.

Logging

Topo writes extension logs to the Topo output channel. Use the log level selector in VS Code's Output view to control which messages are shown.

Development

See the Development Guide for instructions on building, testing, and packaging the extension from source.

Submit Feedback or Report Issues

To submit feedback or report issues, please use GitHub Issues in the extension repository.

License

Apache 2.0