Introduction and Overview
This chapter groups the commands that bridge simple actions from the build container back to the host system. These tools are the normal route for opening files, editing them in host applications, launching host-side commands, accessing the clipboard, or browsing a repository URL from inside the environment.
Technical Details
Host bridges
host-open, host-edit, and host-run bridge simple operations back to the host system. Clipboard integration is provided by host-copy and the emulated xsel and xclip commands. Repository browsing through git-open uses the same host-opening path to launch the site in a browser.
These tools work by sending a request from inside the container to a listener running on the host, over the port named by ROBUILD_CONTROL_PORT, resolved relative to the mapped project path in ROBUILD_HOST_PATH. If either variable is unset, the bridge has nothing to connect to and these commands cannot act on the host. See Files, directories, and variables for the full variable reference.
If a command fails with Cannot connect to host system despite both variables being set, the host-side listener (started by the host launcher script that brought up the container, not by anything inside it) is not currently reachable on that port. This can happen if the listener was not started, was restarted independently of the container, or if the host machine went to sleep or changed network state since the container started. Retrying after a few seconds is often sufficient; if it persists, restart the host-side launcher. This is a connectivity gap between the container and the listener, not a fault in the wrapper scripts themselves: when the listener is reachable, all four commands documented below have been confirmed to work correctly in this environment (see each command's use notes).
Commands
<-h> | - | Show the wrapper's help summary. |
<--help> | - | Show the wrapper's help summary. |
<target> | - | Host-visible file or URL to open. |
Delegates file or URL opening to the host desktop environment.
If the argument contains a colon it is treated as a URL and passed through unchanged. Otherwise it is treated as a file path and mapped back to the corresponding host path when possible. Only files in host-mapped directories can be opened this way.
xdg-open is an alias for the same behaviour inside the environment.
Verified live in this environment: opening a file under /riscos-source printed the resolved host path and returned immediately, having opened the file in the host's default application for it.
<-h> | - | Show the wrapper's help summary. |
<--help> | - | Show the wrapper's help summary. |
<file> | - | Host-visible file to open in an editor. |
Opens a file in the host editor, using ROBUILD_EDITOR when set.
The wrapper falls back through VISUAL and then EDITOR if ROBUILD_EDITOR is not set. The file must be in a host-mapped location so that the container path can be translated back to the host.
A waiting editor command such as subl -w can be useful if you want the wrapper to return only when the file is closed.
Verified live in this environment: the host editor window opened correctly for a test file. With the host's configured editor command set up to wait, the wrapper itself does not return until that editor window is closed, so do not expect an immediate prompt back; this is normal, not a connection failure, and is the same behaviour subl -w above is describing.
<-h> | - | Show the wrapper's help summary. |
<--help> | - | Show the wrapper's help summary. |
<host-command> | - | Host command to execute outside the container. |
<argument> | - | Arguments passed to the host command. |
Delegates a simple non-interactive command to the host machine through the host-control bridge. robuild, the host launcher that starts the container (see robuild), also starts the listener this bridge connects to; that listener is already running on the host by the time a shell inside the container is available, so nothing needs to be run inside the container to create or maintain it.
For recognised file arguments, the wrapper tries to map shared container paths back to their host paths. That works well for ordinary file arguments but is not guaranteed for every command-line syntax.
When output is not connected to a terminal, or when running under an AI-agent environment, the wrapper captures the host command's output and returns it at the end rather than streaming it live.
Verified live in this environment: host-run echo hello-test-12345 connected to the host listener, ran the command, and returned the captured output and a zero exit code, exactly as described above.
<-h> | - | Show the wrapper's help summary. |
<--help> | - | Show the wrapper's help summary. |
Sends text from the container to the host clipboard through the same host-control bridge used by the other host integration commands.
This is the underlying clipboard bridge used by the simplified xclip and xsel compatibility wrappers supplied by the environment.
Verified live in this environment: piping text into host-copy connected to the host listener and returned a zero exit code with no error.
<-h> | - | Show the script's help summary. |
<--help> | - | Show the script's help summary. |
<--remote> | - | Use the named Git remote instead of origin. |
<--show> | - | Print the resolved URL without opening it. |
<--open> | - | Open the resolved URL. This is the default action. |
<site> | - | Open the repository's main web page. |
<source> | - | Open the source browser for the current branch. |
<issues> | - | Open the repository issue tracker page. |
<pr> | - | Open the pull-request or merge-request page for the current branch. |
git-open inspects the current repository's remote URL, recognises the hosting provider, and constructs a browser URL for the repository site, the current branch, the issue tracker, or the pull or merge request page for the current branch.
The default remote is origin. Use --remote name to inspect another configured remote instead. If no operation is supplied, the default is site, which opens the repository's main web page. source opens the source view for the current branch, issues opens the issue tracker page, and pr opens the pull-request or merge-request page for the current branch where the hosting provider supports it.
--show prints the resolved URL without opening it. --open opens the URL in the host browser, which is the normal default behaviour inside this environment. If the current checkout is on a detached HEAD, the tool falls back to the remote's default branch where it can determine one.
The script includes URL handlers for GitHub and GitHub-style sites, GitLab and GitLab-style sites, Savannah, Bitbucket, and AWS CodeCommit. Not every provider supports every operation, so some combinations fail cleanly when the site does not offer a matching web page.