| name | remote-workspace |
| description | Initialize and operate a guarded local-development/remote-execution workspace on Linux, macOS, or Windows PowerShell. Use for new or existing projects that need Git initialization, remote runtime installation, source synchronization, remote Python/tests/experiments/GPU execution, worktree isolation, or protected remote cleanup, including projects that do not yet contain the runtime. |
Remote Workspace
Keep local Git as the source of truth. Run project code only in its mapped
remote workspace.
Initialize
-
Inspect the target directory, existing Git root, and Python package roots.
Never initialize a nested repository accidentally.
-
Obtain REMOTE_WORKSPACE_HOST and either REMOTE_WORKSPACE_BASE or
REMOTE_WORKSPACE_DIR. If absent, ask the user; never invent a server.
-
Preview, then run:
python3 <skill-dir>/scripts/bootstrap.py --dry-run --target <project>
python3 <skill-dir>/scripts/bootstrap.py --target <project>
Pass --host, --remote-base, or --remote-dir when values are not in the
environment. The bootstrapper initializes Git if needed, installs the
runtime, writes ignored local configuration, and runs offline verification.
It records src plus the project root when a top-level src/ exists;
otherwise it records the project root. For other layouts, repeat
--pythonpath <relative-path> or use --no-pythonpath.
Do not use --force without reviewing conflicting files.
Keep the runtime and .remote-workspace/project.json tracked in Git; never
commit .remote-workspace/local.json.
On Windows PowerShell, use python for Python commands and .\sync.ps1
wherever the examples use ./sync.sh.
Verify and bind
From the project root:
python3 remote_run.py --show-context
./sync.sh --show-context
./sync.sh --probe
Require the two mappings to agree. --probe is read-only. Before the first
remote write, also verify the reported Python path, tell the user the exact
target, and obtain authorization:
./sync.sh --init-target
./sync.sh --once --dry-run
./sync.sh --once
--init-target writes only the remote project identity marker. Review
unexpected deletions in the dry run before syncing.
Run
Sync changed code before executing it:
python3 remote_run.py python experiments/example.py
python3 remote_run.py --direct -- pytest tests/
Keep jobs in the foreground so the run lock remains valid. Do not fall back to
local training, evaluation, data generation, or GPU probes when remote access
fails.
For justified cleanup, use a direct command with an auditable reason:
python3 remote_run.py --yes --reason "remove obsolete debug output" \
rm -rf tmp/obsolete-run
Never bypass a block with raw SSH, an opaque shell/Python one-liner, or an
indirect command. Never modify paths outside the mapped project or protected
data/, runs/, checkpoints, submissions, reports, and runner metadata.
