System reference

Most installations do not need anything on this page. Use it when preparing managed, offline, minimal or hardware-connected machines, or when diagnosing an environment-specific issue.

Operating systems

Orcraft supports Windows, Linux and macOS. Every release is built for Windows x64, Linux x86_64, Linux ARM64 and macOS on Apple silicon and Intel, one wheel per platform, and pip installs the one for the machine. It has been validated in these environments:

Other versions and architectures - arm64 Linux, Windows on Arm, Intel Macs - are expected to work wherever Python and PySide6 are available; they simply have not been through the validation matrix above yet.

Windows 10 left mainstream support in October 2025, but it stays in the matrix on purpose: lab and instrument machines often cannot be upgraded, and endpoints run on it perfectly well.

The controller GUI's best experience is on Windows. It needs a desktop session to run. Endpoints have no GUI, so they can run headless - on a server or over SSH.

Linux desktop libraries (controller only)

Desktop Linux installations already include the Qt libraries used by the controller. Use these commands only on a minimal image where startup fails with Could not load the Qt platform plugin "xcb". Endpoints have no GUI and need none of these packages.

First start after an install

The first start of the controller or the endpoint application after an install or an update takes longer: the operating system checks the newly installed code before it runs. The package's compiled code is one file, so the check is paid once: on Windows, Microsoft Defender takes a few seconds on a desktop and up to about half a minute on a small virtual machine; macOS takes about ten seconds; antivirus software on any operating system does the same. The terminal says so and counts the wait. Every later start is immediate.

Endpoint connectivity

What Orcraft opens on the network and how the controller finds an endpoint. Use it to plan firewall rules, choose ports and addresses on machines with several interfaces, and decide whether endpoints are added by name or by IP address. The endpoint's -port and -ip options are given on its command line, in the same way as on Adding endpoints/Run the endpoint.

Ports, addresses and names

Commands

Commands that follow from the table:

For the firewall steps needed by remote endpoints, see Prerequisites/Remote endpoints.

Host-name resolution

An endpoint added by host name is resolved on the machine that runs the controller, by that machine's own resolver: its DNS server, its hosts file and, on most systems, mDNS (name.local) as a fallback. The controller pings the name, then name.local, then the last address it knew. A name that works from one PC can therefore fail from another, and the place to check is always the controller's machine. Ping the name there; the first line of the output shows which address the name resolved to:

Hosts with more than one address

A machine connected by both Ethernet and Wi-Fi has two IPv4 addresses, and a name lookup can return either of them. The controller and the endpoint talk over whichever address answers, but the address shown on the card is the one the controller's last lookup returned, so it can differ from one lookup to the next. When one of the interfaces is disconnected, the name can keep resolving to that interface's address until the cached answer expires, and the card shows Offline while the machine is reachable on its other address. To hold a host to one address, add the endpoint by IP address instead of by name, or keep only one of its interfaces on the network the controller uses.

Stale name lookups

Resolvers cache their answers. After an endpoint machine changes address, disconnects an interface or is renamed, the controller's machine can keep pinging the old address for minutes. Flush the cache on the controller's machine, then wait for the card's next poll:

On Windows, ping counts a "Destination host unreachable" reply from the controller's own machine as an answer, so a stale address can show the card as Online rather than Offline. The flush applies in the same way.

IPv6 link-local answers

Some resolvers return an IPv6 link-local address (fe80::…) ahead of the IPv4 one; a plain ping of the name shows it in the first line. Such an address is tied to one network interface of the controller's machine and stops working when that machine moves between Wi-Fi and Ethernet. If connections to an endpoint are unstable while its name resolves that way, add the endpoint by its IPv4 address.

Several endpoint applications on one machine

The endpoint application is the program started with orcraft-endpoint run. One running copy listens on one port. A machine normally runs one copy, and the controller registers that machine as one endpoint.

Each machine is added once

A controller registers a machine as one endpoint. If the machine is already in the Endpoints frame, adding it again is refused, even with a different port.

Several tests can still use the same machine. By default, runs wait for each other on that endpoint. If tests may run on the machine at the same time, set the shared option on the endpoint field in the test.

A second endpoint application for another controller

A machine can run a second copy of the endpoint application on another port, so that another controller can use the machine. Each controller then talks to its own endpoint application. The two controllers work independently, and packages uploaded through one endpoint application do not affect the other.

Start the second copy with a port of its own, and register it in the second controller with that port:

Use this only when the tests of the two controllers do not compete for the same resource on the machine, such as a device, a port or a file. If they do, register the same endpoint application in both controllers instead. Runs from both controllers then wait for each other, or run at the same time when the test marks the endpoint shared.

Both copies report the same host name to the controller. The Info dialog of an endpoint shows its Port, which tells the two copies apart.

Requirements for a second endpoint application

The endpoint application keeps its files under the directory it was started from and in the Python environment it was installed in. A second copy therefore needs the following:

Security material

The authorization token and the certificates are stored once per machine. All copies of the endpoint application on the machine use the same ones.

Endpoints reached through SSH

An endpoint added with Connect through SSH (Adding endpoints/Connecting an endpoint via SSH) is reached through a tunnel the controller opens with the ssh client of its own computer. The controller only supervises that client: it starts it, notices when it exits and starts it again after a pause that grows from a few seconds to half a minute, and turns its last words into the sentence the card shows.

Permissions and storage

Orcraft itself does not require administrator or root access.

Shells and terminals

Terminal output

The endpoint and test framework use ANSI colors and Unicode box-drawing characters.

If a Windows console shows raw escape sequences, use Windows Terminal or enable virtual-terminal processing once for the current user:

If box-drawing characters appear as ?, use Windows Terminal or run chcp 65001 in the classic console. The controller GUI renders output itself and is unaffected.

Log files

Runs are saved as .ansi files with their colors embedded.

Endpoint environment

A program that a test starts inherits the environment of the endpoint application. If a test needs a variable on the endpoint machine, such as a tool path or a display setting for a graphical program, define it where the auto-started endpoint reads its environment, then restart the endpoint. The example below defines MY_TOOL_HOME; replace the name and value with your own.

Windows

The Task Scheduler task starts the endpoint executable directly, so the variable must be in the account's environment. Define it once from a command prompt:

Then stop the endpoint with Ctrl+C in its console window, close the window, and sign out and in again. The task starts the endpoint at logon with the new variable.

Linux

The systemd user service opens the endpoint in an interactive bash shell, which reads ~/.bashrc. Add the variable there and start the service again:

echo 'export MY_TOOL_HOME=/opt/mytool' >> ~/.bashrc
systemctl --user start orcraft-endpoint

Stop the running endpoint first with Ctrl+C in its terminal window and close the window, otherwise the new instance finds the port in use.

macOS

The launch agent opens the endpoint in Terminal.app, whose login shell reads ~/.zshrc. Add the variable there and start the agent again:

echo 'export MY_TOOL_HOME=/opt/mytool' >> ~/.zshrc
launchctl kickstart -k gui/$(id -u)/com.orcraft.endpoint

Stop the running endpoint first with Ctrl+C in its Terminal window and close the window.

The same files apply to the restart the endpoint performs after an update from the controller. An endpoint launched by hand from a terminal uses that terminal's environment instead, so a variable exported in that terminal before orcraft-endpoint run also works.

Python libraries

pip installs these libraries automatically along with the orcraft package.

Packages a suite needs on top of these, for a tool it drives or a protocol it speaks, come from the suite's requirements.txt: the controller installs them into the endpoint application's Python when it uploads the suite. See Suite requirements.

Optional integrations

Internet access

Connected machines install with pip install orcraft; isolated machines install from a copied wheel file. Test traffic stays on your own network. Two controller conveniences make outbound calls and fail quietly when unavailable:

Git

Only needed for suites kept in Git repositories. Archive-based suites skip this integration.

Installing for the first time? Start with Prerequisites, then Getting started.