# Create and deploy a custom Topo Project

## In this learning path

- [Introduction](https://learn.arm.com/learning-paths/cross-platform/create-your-own-topo-project/)
- [Learn about Topo Projects](https://learn.arm.com/learning-paths/cross-platform/create-your-own-topo-project/overview/)
- [Clone and deploy the Hello World Topo Project](https://learn.arm.com/learning-paths/cross-platform/create-your-own-topo-project/hello-world-project/)
- [Modify the Hello World Topo Project](https://learn.arm.com/learning-paths/cross-platform/create-your-own-topo-project/modifying-hello-world/)
- [Create a new Topo Project from an empty directory](https://learn.arm.com/learning-paths/cross-platform/create-your-own-topo-project/creating-a-new-project/)
- [Use Agent Skills to author Topo Projects](https://learn.arm.com/learning-paths/cross-platform/create-your-own-topo-project/agent-skills/)
- [Next Steps](https://learn.arm.com/learning-paths/cross-platform/create-your-own-topo-project/_next-steps/)

## About this Learning Path

| Skill level:         | Introductory                       |
|----------------------|------------------------------------|
| Reading time:        | 30 min                             |
| Last updated:        | 15 Jul 2026                        |

| Author:                       | Tomas Agustin Gonzalez Orlando, Arm [GitHub](https://github.com/tgonzalezorlandoarm) [LinkedIn](https://linkedin.com/in/tgorlando) |
|-------------------------------|-----------------------------------------------------------------------------------------------------------------|
| Arm IP:                       | [Neoverse](https://support.arm.com/?tab=compute-ip&Product%20Type=Infrastructure%20Processors) [Cortex-A](https://support.arm.com/?tab=compute-ip&Product%20Type=Application%20Processors) [Cortex-M](https://support.arm.com/?tab=compute-ip&Product%20Type=Microcontrollers) |
| Tags:                         | [Containers and Virtualization](https://learn.arm.com/tag/containers-and-virtualization) [Linux](https://learn.arm.com/tag/linux) [macOS](https://learn.arm.com/tag/macos) [Windows](https://learn.arm.com/tag/windows) [Topo](https://learn.arm.com/tag/topo) [Docker](https://learn.arm.com/tag/docker) [SSH](https://learn.arm.com/tag/ssh) |

### Who is this for?
This is an introductory topic for embedded, edge, and cloud software developers who want to create their own Topo Projects to be natively deployed with Topo.

### What will you learn?
Upon completion of this Learning Path, you will be able to:
- Explain the purpose and structure of a Topo Project
- Clone and deploy an existing Topo Project and modify it by adding new clone-time parameters
- Create a new Topo Project from a Docker Compose project
- Add x-topo metadata for configurable parameters, deployment guidance, and hardware requirements
- Locate and install Agent Skills to assist with creating and reviewing Topo Projects

### Prerequisites
Before starting, you will need the following:
- Completion of the [Deploy containerized workloads to Arm-based Linux targets with Topo](https://learn.arm.com/learning-paths/cross-platform/deploy-containerized-workloads-with-topo/) Learning Path.
- 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](https://learn.arm.com/install-guides/docker/).
- Basic familiarity with containers and CLI tools

### Summary
You’ll author and deploy Topo Projects to Arm-based Linux targets over SSH. First, you’ll clone and run a starter project to confirm your setup, then edit its `compose.yaml` to add `x-topo.parameters` entries that make the greeting emoji configurable at clone time. Next, you’ll create a new project from an empty directory that serves a simple web page with configurable text and color while learning the core pieces of a project: standard Compose services, `x-topo` metadata, and build arguments for Arm Linux targets. You’ll also see where to find optional Agent Skills to assist with creating or converting projects, and how to recognize a successful deployment by observing the configured behavior on the target.

### Frequently asked questions
<details>
<summary>What should I see after running `topo clone` on the Hello World project?</summary>
You should see a new directory at the path you provided (for example, `~/topo-welcome`) and clone output that includes lines like `Copy files` and `Cloning into ...`. After cloning, the project’s services can be deployed to the Arm-based Linux target as shown in the steps.
</details>

<details>
<summary>Where do I add a new clone-time argument such as a greeting emoji?</summary>
Add it under the `x-topo` parameters section in `compose.yaml`, alongside the existing `GREETING_NAME` parameter. Define the parameter name and metadata there so Topo can surface it during cloning.
</details>

<details>
<summary>How do I confirm that my new argument is being used?</summary>
Clone and deploy the updated project, then check the running service’s behavior for your change. For example, the Hello World greeting should include the emoji you configured, or the sample webpage should reflect your chosen text and color.
</details>

<details>
<summary>What are the essential parts of a minimal Topo Project I create from scratch?</summary>
Include a `compose.yaml` with standard Compose services, an `x-topo` metadata block, and project parameters wired to Docker build arguments when needed. The container image should be built for Arm Linux targets.
</details>

<details>
<summary>When should I use Agent Skills, and which ones are available for projects?</summary>
Use Agent Skills as optional aids when you want help creating or converting a project into a Topo Project. Topo provides `topo-project-context` for reference about `x-topo` and CLI behavior and `topo-project-bootstrap` to help convert a repository into a Topo Project.
</details>