Tao Run On Virtualenv

NVIDIAOfficialCreated by NVIDIA Corporation

Skill
Tool integration
Automation and integrations
Apache-2.0
Medium risk
Has scripts

From the author

Run a Python training/eval script directly in an existing local virtualenv — no docker, no container. Implements the four-verb consumer contract (submit/status/logs/cancel) over a vendored process-lifecycle runner with durable on-disk state, PID-reuse-safe identity, and process-group cleanup. Use for docker-free local execution, plain-Python model scripts, fast HPO/AutoML trial smokes, or hosts where containers are unavailable. Trigger phrases include "run in my venv", "no docker", "virtualenv execution", "local python training", "run this training script directly".

— the description by NVIDIA Corporation

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The tao-run-on-virtualenv skill provides a mechanism to run Python scripts natively using an existing local virtual environment. It bypasses containerization, making it suitable for environments where Docker is unavailable or for rapid, lightweight experimentation. The skill implements a standard four-verb interface (submit, status, logs, cancel) to manage the lifecycle of local processes, ensuring durable state tracking and process group cleanup.

What it does

Executes Python scripts directly using a specified virtualenv interpreter.
Manages job lifecycles with submit, status, logs, and cancel operations.
Provides durable on-disk state tracking for job records.
Ensures process group cleanup to prevent orphaned processes.
Supports environment variable injection for secure configuration handling.
Integrates with local job recording systems for auditability.

When to use it

When running plain Python scripts that do not require containerized environments.
When Docker or other container runtimes are unavailable on the host.
When minimizing startup overhead for fast HPO or AutoML trial loops.
When working on single-node development environments.

Advantages

Eliminates container startup latency and dependency management overhead.
Operates natively on the host system using existing virtual environments.
Provides robust process lifecycle management and cleanup.
Supports secure handling of environment variables without exposing them in command arguments.

Usage examples

“Run my training script train.py in the local virtualenv located at /opt/venv.”: The agent initializes the job record, configures the runner to use the specified venv, and launches the training process in a detached state.
“Check the status of my current virtualenv training job.”: The agent queries the runner's durable state files and returns the current status (e.g., RUNNING, COMPLETE, or ERROR).
“Cancel the active training job running in the virtualenv.”: The agent triggers the cancellation process, which uses a durable group guardian to safely terminate the process group.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/nvidia/tao-run-on-virtualenv/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip tao-run-on-virtualenv.zip -d .agents/skills

Documentation by NVIDIA Corporation

Virtualenv — docker-free local Python execution

Standalone install? If this session was not initialized by the TAO skill bank plugin, run the tao-setup skill first (host preflight, credentials, cross-skill discovery).

The virtualenv platform runs a Python script natively in an existing venv — as an argv vector whose first element is <venv>/bin/python, never through a shell, never activating anything. The vendored runner (references/virtualenv_runner.py) is this platform's "native CLI" — the role docker/kubectl/sbatch play elsewhere — and owns only the process lifecycle. Job records stay with tao_job_record.py; specs are authored by the agent, exactly like every other platform.

When to use

The workload is a plain Python script (its dependencies pip-installed in a venv), not a TAO container action.
No docker on the host, or container startup cost isn't worth it (fast smokes, AutoML trial loops over lightweight models).
Single node only. For TAO container actions use tao-run-on-docker; for clusters use -slurm / -kubernetes.

Preflight

# 1. The venv is real and has an executable interpreter.
[ -f "$VENV/pyvenv.cfg" ] && [ -x "$VENV/bin/python" ] || echo "MISSING: $VENV is not a venv"
# 2. The script's top-level imports resolve inside it (catches wrong-venv early);
#    substitute the real modules your script imports.
"$VENV/bin/python" -c "import torch" || echo "MISSING: script dependency not in $VENV"
# 3. GPU visibility only if the script needs CUDA.
nvidia-smi >/dev/null 2>&1 || echo "note: no GPU visible (fine for CPU scripts)"

No credentials are required by the platform itself; model-specific env vars (e.g. HF_TOKEN) pass through by NAME with -e (values never land on argv).

Storage

Tier A by definition — everything is local paths. Datasets must already be on local disk (stage with tao-data-io first if they live in S3). Outputs land in the job record's results_dir, which IS the runner's --job-dir.

Execution — the four verbs

$BANK = ${TAO_SKILL_BANK_PATH}; $RUNNER = $BANK/skills/platform/tao-run-on-virtualenv/references/virtualenv_runner.py.

submit

Author the spec (if the script takes one) at a local path — nested dicts, never flat dotted keys — and lint the assembled command with redact_secrets.py lint.

Open the record — mints the id, binds results_dir BEFORE launch:

JOB_ID=$("$BANK/scripts/tao_job_record.py" open --platform virtualenv \
  --image "$VENV/bin/python" --network-arch "$ARCH" --action "$ACTION" \
  --storage-tier A --results-root "$RESULTS_ROOT")
RESULTS_DIR="$RESULTS_ROOT/$JOB_ID"

Launch detached (the runner writes a durable wrapper that gates start, records identity, and cleans up the process group on exit):
```
set -a; source /path/to/.env; set +a   # omit if already exported
python3 "$RUNNER" submit --job-dir "$RESULTS_DIR" --venv "$VENV" \
  --script train.py --job-id "$JOB_ID" --config-path "$SPEC" \
  --arg train --arg=--config={config_path} --arg=--out={results_dir} \
  --gpu-ids 0 -e HF_TOKEN
```
Placeholders {config_path} {results_dir} {job_id} render inside --arg tokens. A token starting with - must use the --arg=TOKEN form (argparse). --gpu-ids sets CUDA_VISIBLE_DEVICES; --gpus 0 hides GPUs; neither reserves anything.

Record RUNNING with the pid the runner printed:

"$BANK/scripts/tao_job_record.py" mark "$JOB_ID" --state RUNNING --backend-ref "pid:<pid>"

One submit per job dir — a retry gets a NEW record (--retry-of), never a re-submit into the same dir.

status

python3 "$RUNNER" status --job-dir "$RESULTS_DIR"   # {"status": "...", ...}

Prints the fixed vocabulary directly: PENDING RUNNING COMPLETE ERROR CANCELED UNKNOWN — no mapping table needed. Status is derived from durable files (exit_status.json, launcher identity) and is safe to poll from any process, any time, including after reboots of the polling agent. On a terminal status, mark the record.

logs

python3 "$RUNNER" logs --job-dir "$RESULTS_DIR" --tail 200

cancel

python3 "$RUNNER" cancel --job-dir "$RESULTS_DIR"
"$BANK/scripts/tao_job_record.py" mark "$JOB_ID" --state CANCELED --source agent

Cancel marks first (a not-yet-started wrapper self-cancels at its start gate), then uses a durable group guardian and Linux pidfds for SIGTERM→SIGKILL. The guardian prevents PGID reuse during discovery; a pidfd pins each target across the observation/signal boundary. already_terminal in the reply means the job finished before the cancel — mark the record with the status it reports instead.

Platform caveats

Linux active cancellation. Safe active-process termination requires procfs, pidfd_open, and pidfd_send_signal. On another POSIX host the ps/pgrep fallback can prove a group is empty, but cancellation of active members returns UNKNOWN instead of risking a reused numeric PID or PGID.
No multi-node, no image resolution — there is no container. The "image" recorded is the venv's interpreter path.
The runner never downloads anything. Remote inputs are the agent's job to stage first (tao-data-io).

Files

ATTRIBUTION.mdAdded by AutoGineer933 B
BENCHMARK.md7.0 KiB
LICENSELicence file added by AutoGineer11.2 KiB
SKILL.md6.3 KiB
config/skillspector-baseline.yaml1.7 KiB
evals/evals.json1022 B
references/skill_info.yaml605 B
references/tests/test_virtualenv_runner.pyScript31.7 KiB
references/virtualenv_group_supervisor.pyScript15.9 KiB
references/virtualenv_runner.pyScript46.2 KiB
skill-card.md4.7 KiB
skill.oms.sig5.7 KiB

BENCHMARK.md

Skill Benchmark: tao-run-on-virtualenv

✅ Overall verdict: PASS — Recommended for publication

Publication Recommendation

Recommended for publication based on the completed evaluation evidence in this report.

Evaluation Metadata

Skill: tao-run-on-virtualenv
Evaluation date: 2026-10-16
Evaluator version: 1.5.6
Agents: Claude Code (aws/anthropic/bedrock-claude-opus-4-8), Codex (openai/openai/gpt-5.5)
Tasks: 1 evaluation tasks (1 positive)
Dataset digest: sha256:9b5194d2d51b31e12c9a2ba1184b419360d32ffea6d7a3898b853c2f4f4130c9 (skill-evaluator-dataset-snapshot/1)
Attempts per task: 1
Environment: k8s-sandbox
Tier 2 evidence: required for publication
Tier 3 evidence: required for publication

Each task attempt ran in its own isolated sandbox pod.

What This Report Answers

The three-tier evaluation checks whether the skill:

is safe to use;
produces correct answers;
is discovered and activated when needed;
helps the agent complete the user's goal and expected workflow; and
avoids wasted skill and tool usage.

Results at a Glance

Measure	Claude Code (Baseline → Skill Uplift)	Codex (Baseline → Skill Uplift)
Overall	94.7% — baseline ran, but no comparable score was available; uplift unavailable	75.4% — baseline ran, but no comparable score was available; uplift unavailable
Security	100.0% → 100.0% (±0.0 points)	100.0% → 100.0% (±0.0 points)
Correctness	0.0% → 100.0% (+100.0 points)	0.0% → 100.0% (+100.0 points)
Discoverability	100.0% — baseline ran, but no comparable score was available; uplift unavailable	0.0% — baseline ran, but no comparable score was available; uplift unavailable
Effectiveness	0.0% → 100.0% (+100.0 points)	16.7% → 78.3% (+61.6 points)
Efficiency	73.3% — baseline ran, but no comparable score was available; uplift unavailable	99.5% → 98.6% (-0.9 points)

How to read this table: baseline is the same task attempted without the target skill. Scores are rounded to one decimal; threshold-adjacent values use additional precision so their displayed band matches the verdict. Uplift is derived from those displayed scores and shown in percentage points.

Example: 47.0% → 92.0% (+45.0 points) means the skill-assisted run scored 92.0%, 45.0 percentage points above its 47.0% no-skill baseline.

A partial dimension was calculated from only the available configured signals; review the detailed report before relying on it.

Token Usage

Actual Tier 3 execution usage is reported for every observed agent/case pair and both conditions.

Agent	Dataset case	With skill	Without skill	Delta	Change	Coverage
claude-code	All cases	94,467	276,254	-181,787	-65.80%	skill 1/1; base 1/1
claude-code	tao-run-on-virtualenv-basic	94,467	276,254	-181,787	-65.80%	skill 1/1; base 1/1
codex	All cases	13,787	13,883	-96	-0.69%	skill 1/1; base 1/1
codex	tao-run-on-virtualenv-basic	13,787	13,883	-96	-0.69%	skill 1/1; base 1/1
ALL AGENTS	Dataset aggregate	108,254	290,137	-181,883	-62.69%	skill 2/2; base 2/2

Prompt tokens include cached reads, so total tokens are prompt + completion (cached is not added twice). The Efficiency score uses (prompt - cached) + completion. N/A means the relevant trajectory counters were not available; coverage is never estimated.

Tier Status

Tier	Purpose	Status	Evidence
Tier 1	Static validation	PASSED WITH OBSERVATIONS	11 validator(s); 33 finding(s)
Tier 2	Semantic deduplication	PASSED	2 validator(s); 0 finding(s)
Tier 3	Live agent evaluation	PASS	2 agent(s); 1 task(s)

Findings and Observations

<details> <summary>Show detailed findings and successful checks</summary>

MEDIUM QUALITY/quality_correctness: SKILL_SPEC recommended field missing: 'metadata.tags' (skills/platform/tao-run-on-virtualenv/SKILL.md)
MEDIUM QUALITY/quality_discoverability: Description uses first/second person (skills/platform/tao-run-on-virtualenv/SKILL.md)
MEDIUM SCHEMA/frontmatter_field_placement: Root field 'tags' is ignored; use 'metadata.tags' (skills/platform/tao-run-on-virtualenv/SKILL.md)
MEDIUM SCHEMA/folder_hierarchy: Unexpected nesting depth for general skill (skills/platform/tao-run-on-virtualenv)
MEDIUM SCHEMA/body_recommended_section: Missing recommended section: '## Instructions' (skills/platform/tao-run-on-virtualenv/SKILL.md)
28 additional finding(s) are available in the full evaluation artifacts.

</details>

Scoring Methodology

<details> <summary>Show dimension definitions, source signals, and thresholds</summary>

Dimension	Question	Scored signals
Security	Is it safe to use?	`security` (100%)
Correctness	Is the answer correct?	`accuracy` (100%)
Discoverability	Was the right skill loaded when needed?	`skill_execution` (100%)
Effectiveness	Did the skill help complete the task?	`goal_accuracy` (50%) + `behavior_check` (50%)
Efficiency	Did it avoid wasted tool calls and token usage?	`skill_efficiency` (50%) + `token_efficiency` (50%)

Dimension bands: PASS at 50% or above; NEUTRAL from 40% to below 50%; FAIL below 40%.
Overall Tier 3 lift: PASS at +5 points or more; FAIL at -10 points or less; values between those bands are NEUTRAL.
Overall verdict: PASS only when every configured dimension passes for at least one supported agent. Lift is reported as diagnostic evidence and does not override this gate.
The 50% attempt pass threshold is a separate per-task gate; it is not the dimension pass threshold.
Effectiveness is the equal-weight mean of goal completion (goal_accuracy) and expected workflow adherence (behavior_check).
Efficiency is 50% tool-call productivity (the backward-compatible skill_efficiency wire id) and 50% token_efficiency. Positive-case skill routing is scored under Discoverability, not Efficiency; a negative case without a routing target is N/A. N/A sources are omitted, remaining weights are renormalized, and the dimension is marked partial.

Signals present in this run:

security (Security): unsafe operations, secret leakage, and unauthorized access.
skill_execution (Skill Execution): whether the expected skill was selected, decoys were avoided, and the workflow executed.
skill_efficiency (Tool Productivity): tool-call productivity (legacy wire id; routing is scored under Discoverability).
accuracy (Accuracy): final-answer correctness against the reference answer.
goal_accuracy (Goal Accuracy): whether the user's goal was achieved.
behavior_check (Behavior Check): whether the expected workflow behavior was followed.
token_efficiency (Token Efficiency): actual uncached prompt plus completion usage (50% of Efficiency).

</details>

Freshness

Regenerate this benchmark when the skill, evaluation dataset, target agent/model, evaluator version, environment, or scoring policy changes.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Declares allowed tools, Needs Python, Needs Node.js

The author says: Requires a local Python virtualenv (pyvenv.cfg + bin/python) with the training script's dependencies installed. Linux with procfs and pidfd signaling is required for active job cancellation; other POSIX hosts can run jobs and prove empty groups but fail closed rather than signal numeric process IDs. No nvidia-tao-sdk, no docker.

Security

What our scanner noticed· Medium risk

Large base64-encoded blobs
Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

NVIDIA Corporation

Publisher

NVIDIA (Official)

Source

NVIDIA/skills · skills/tao-run-on-virtualenv · commit fce3cca

Licence

Apache License 2.0 (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE-APACHE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

AutoGineer is not affiliated with or endorsed by NVIDIA Corporation or NVIDIA.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download tao-run-on-virtualenv.zip