tcd — Device Connect Topo deploy driver

tcd exposes Arm Topo edge deploy workflows on the Device Connect mesh as a topo_deployer device. Agents can health-check, list templates, clone, deploy, and stop Compose projects on remote Arm64 targets over SSH — on D2D or Portal.

For local Docker Engine control (socket, in-cluster, docker compose on the same host), use the sibling project dcd instead.

License: Apache-2.0

When to use tcd vs dcd

Scenario	Driver	device_type
Raspberry Pi / Jetson over SSH; build on laptop, transfer images, compose up on board	tcd	topo_deployer
Docker on this machine or DinD; per-container exec/logs	dcd	docker_host
Gateway with both	Run both drivers (different device ids)

Install

cd ~/src/tcd
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Install the topo CLI on PATH for non-sim mode.

Quick start — D2D (sim)

export DEVICE_CONNECT_ALLOW_INSECURE=true
tcd --sim --device-id topo-deploy-1 --default-target ssh://pi@edge.local

Quick start — real deploy

From a directory with compose.yaml:

export TOPO_TARGET=ssh://pi@192.168.1.10
export DEVICE_CONNECT_ALLOW_INSECURE=true
tcd --device-id topo-edge-1 --default-project-dir ~/my-stack

Then invoke deploy with {} to use defaults, or pass an explicit spec.

Portal

tcd --portal \
  --portal-credentials ~/.config/device-connect/topo-deploy.creds.json \
  --nats-credentials-file ~/.config/device-connect/topo-deploy.creds.json

RPC reference

Function	Maps to
get_status / ping_topo	Driver + topo --version
check_health	topo health --output json
list_templates	topo templates --output json
deploy	topo deploy --target …
stop	topo stop --target …
clone_project	topo clone …

Event: deploy_finished — after successful deploy

Deploy spec

{
  "target": "ssh://pi@192.168.1.10",
  "project_dir": "/path/with/compose.yaml",
  "no_registry": false,
  "skip_project_checks": false
}

target may be omitted if TOPO_TARGET, --default-target, or driver default is set.

Configuration

Variable	Description
TOPO_TARGET / TCD_DEFAULT_TARGET	Default SSH target
TCD_DEFAULT_PROJECT_DIR	Default compose project directory
TCD_TOPO_BINARY	Path to topo binary
TCD_SIM	Simulated backend
DEVICE_CONNECT_*	Same as other drivers (portal, D2D, NATS)

CI

GitHub Actions: ruff + pytest (Python 3.12/3.13, sim backend). See .github/workflows/ci.yml.

Related

• dcd — Docker Engine driver
• topo — underlying CLI
• DESIGN.md — architecture and split rationale