OpenParable
Skip to content
← Back to skills

Tt Connect Remote Device

Apps & Automation
tt-connect-remote-device

Tt Connect Remote Device is an Agent Skill for apps & automation published in the tenstorrent/tt-forge repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Set up and verify remote connection to Tenstorrent hardware. Provides tools for running kernels, copying files, and reading logs on remote devices.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/tenstorrent/tt-forge/blob/HEAD/skills/tt-connect-remote-device/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/tt-connect-remote-device, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Prerequisites

All tools are in the scripts/ directory relative to this skill. Invoke them with the full path.

Before doing anything else, run the smoke test to verify your remote setup:

<path-to>/tt-connect-remote-device/scripts/smoke-test.sh

If the smoke test fails, STOP. Do NOT continue. Ask the user to fix their remote setup first.

If the smoke test fails due to remote.conf not existing, STOP, offer to help them create it from scripts/remote.conf.example. Then work on getting the smoke test passing before exploring or continuing.

Tools Available

NOTE: flags on run-test.sh must come before the file argument. You can use --help if unsure on how to use.

NOTE: run-test.sh will copy the file. You do not need to copy the test file each time.

scripts/run-test.sh /path/to/kernel.py                # Run in functional simulator (default)
scripts/run-test.sh --hw /path/to/kernel.py            # Run on real hardware (final validation)
scripts/run-test.sh --hw --emit-runner /path/to.py     # Run + emit C++ kernels and Python runner
scripts/copy-file.sh /path/to/file.py                  # Copy a file TO the remote
scripts/copy-from-remote.sh /remote/path ./local_dir/  # Copy a file FROM the remote
scripts/remote-run.sh <command>                         # Run an arbitrary command on the remote

By default, run-test.sh uses the functional simulator (ttlang-sim). Use --hw for real hardware. Iterate with the simulator first. Only move to --hw for final validation or if the simulator has a bug that blocks your work. Note: the simulator cannot run TT-Metal C++ programs, so export workflows always require --hw.

Reading remote logs (output is saved, not streamed):

scripts/remote-run.sh cat /tmp/ttlang_test_output.log        # Full log
scripts/remote-run.sh tail -100 /tmp/ttlang_test_output.log  # Last 100 lines
scripts/remote-run.sh cat /tmp/ttlang_test_output.log | grep -i "error"  # Search log
scripts/remote-run.sh cat /tmp/ttlang_initial.mlir           # Initial MLIR
scripts/remote-run.sh cat /tmp/ttlang_final.mlir             # Final MLIR

NOTE: Grep with quoted patterns containing spaces does not work via remote-run.sh due to quoting through the SSH+docker chain. Always pipe through grep locally: remote-run.sh cat /path/to/file | grep "pattern"