Adding endpoints

Register an endpoint so the controller can distribute test packages and execute steps on it: install and run the endpoint application on the machine, add the machine in the controller, sign in and license it. This page follows an endpoint the controller reaches directly over the network; a machine whose port the controller cannot reach, behind a bastion or on another network, is added through SSH after the same installation.

Install the endpoint

Install from PyPI

If the endpoint machine is connected to the internet, install it the same way as the controller, in the activated virtual environment:

pip install orcraft

Install from a wheel file

If the machine has no internet access, download the wheel on a connected machine, copy it over and install it directly. A release carries one wheel per platform, so take the file for the machine's platform. Every wheel is built for Python 3.14's stable ABI, so the same file serves a later Python 3 as well. In the activated virtual environment:

Platform	Command
Windows x64	`pip install orcraft-<version>-cp314-abi3-win_amd64.whl`
Linux x86_64	`pip install orcraft-<version>-cp314-abi3-manylinux1_x86_64.manylinux_2_5_x86_64.whl`
Linux ARM64	`pip install orcraft-<version>-cp314-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl`
macOS, Apple silicon and Intel	`pip install orcraft-<version>-cp314-abi3-macosx_10_15_universal2.whl`

Run the endpoint

More details on ports, addresses, host-name resolution and running more than one endpoint application on a machine can be found in System reference/Endpoint connectivity.

Insecure endpoint connection

For a fast setup on a trusted, isolated local network, the endpoint can be run without security enabled:

orcraft-endpoint run -secure disabled

The first start after an install takes longer while the operating system checks the new files, up to about half a minute; the terminal counts the wait, and every later start is immediate (System reference/First start after an install).

This is how the endpoint's own terminal output looks like when running insecurely:

Orcraft Endpoint (v0.1.0.dev304)
================================


[OrcraftEndpoint] Orcraft Endpoint (v0.1.0.dev304) started on [::]:50051
[OrcraftEndpoint] Secure connection inactive. Using insecure transport: Secure transport disabled.

In the controller, add the endpoint by clicking Add in the Endpoints frame.

Enter the endpoint's host name or IP and port, with security disabled. The two other parts of the dialog stay as they are: Connect through SSH is for a machine reached through SSH, and Custom Labels describe what the machine is for tests that ask for any available endpoint.

The endpoint appears in the Endpoints frame, connected without security.

The card answers, so the endpoint application is installed and reachable, but its status is Locked: a remote endpoint runs tests only once it is licensed, and licensing takes a signed-in controller. The card's license row says Ready for license, and the localhost card says Not signed in. Both are settled in the next step.

Open the controller's Account tab and click Sign in. The sign-in page opens in your browser, and the tab shows the code to approve there:

Sign in on the page, or create your account there, and approve the controller. The tab signs in on its own once you do, and shows who is signed in, the plan, how long it runs and how many of its machine slots are in use. A new account is on Free: tests on your own computer need no account at all, and two remote endpoint machines can be licensed to it, from one signed-in controller at a time. A Team has as many slots as it bought, shared by its members. The pricing page describes both.

Back in the Execution tab, right-click the endpoint's card and choose Activate License:

The controller reserves one of the plan's machine slots and pushes the license to the endpoint. The card reads Activating… for a moment, then Licensed, and its status turns Ready:

A Ready status means the endpoint can now run test steps remotely. The license is the machine's: it holds for three days and a signed-in controller renews it every day, so the machine stays licensed as long as a controller of yours signs in now and then. Revoke License in the same menu hands the slot back when a machine leaves the lab. The Licensing page explains the plans, the renewal and the license states of the card.

Not interested in a secure connection right now? Skip ahead to the Tutorial and come back to security setup later.

Secure endpoint connection

For a secure deployment, follow the security setup procedure in the controller's Security tab:

Once that's done, run the endpoint with authentication enabled, which is the default:

orcraft-endpoint run

This is how the endpoint's own terminal output looks like when running securely:

Orcraft Endpoint (v0.1.0.dev304)
================================


[OrcraftEndpoint] Orcraft Endpoint (v0.1.0.dev304) started on [::]:50051
[OrcraftEndpoint] Secure connection enabled with mTLS transport and endpoint auth token.

If the endpoint was already added without security, right-click it in the controller and edit it to enable security instead of adding it again:

Otherwise, add the endpoint the same way as before, with the security option checked (enabled), and license it as above. Either way, it appears in the Endpoints frame, connected with security:

A Ready status means the endpoint can now run test steps remotely.

Run Hello Endpoint test

With the endpoint Ready, run a test on it. The tutorial suite's Hello Endpoint test sends one step to the endpoint; the step runs the hostname command there and logs the machine's name. Add the suite as in Getting started, select Hello Endpoint and click the pencil at the right of Test Endpoint to choose the endpoint:

Click Run and confirm. The log shows the step's Target Endpoint and the line Hello from with the endpoint's name, and the run row reads Pass:

The Hello Endpoint test page of the tutorial reviews the test's code. You can now proceed to the Tutorial.

Connecting an endpoint via SSH

When the controller cannot reach the endpoint's port, because the machine sits on another network or behind a bastion host, the controller reaches it through an SSH tunnel it opens itself. It runs the ssh client of its own computer, with your keys, agent, configuration and known hosts, exactly as a hand-typed ssh -N -L would, and keeps the tunnel up for as long as the card exists. Keys only: the controller never asks for a password nor passes one on.

Install and run the endpoint on its machine as above. Then add it with Connect through SSH ticked:

Host name or IP and port are the endpoint as the SSH host sees it: the far end of the tunnel. When the SSH host is the endpoint machine itself, that is its own name.
SSH Host is the machine you log into: the bastion, or the endpoint machine itself. SSH User, SSH Port and Key File are what you would type after ssh; left blank, they come from your SSH configuration and agent.

The first time a host sees your key, the card's menu has Install SSH Key: it opens a terminal on the command that appends your public key to the host's authorized keys, asking that host's password once, there, and makes a key pair for you first when you have none. From then on the tunnel opens without a prompt.

The card shows the way in where the others show their address, marked with the tunnel sign, and is otherwise like any other: locked until the controller is signed in and the machine licensed as above, Ready after that.

Its Info names the way in and the tunnel's state with the local port it uses:

A tunnel that drops is reopened by itself, with a growing pause between attempts, and while it is down the card's status reads Offline with the reason on hover: a key the host did not accept, a host that forbids TCP forwarding, a changed host key. The system reference lists what the tunnel needs on both machines.

Start the endpoint automatically

Optional, and a single command. Registering the endpoint for auto-start means it comes back by itself at your next logon, so a lab machine returns to service after a reboot without anyone having to remember to start it:

orcraft-endpoint startup

Any options you pass are baked into the registration, so the endpoint comes back exactly the way you run it by hand:

orcraft-endpoint startup -port 50052 -secure disabled

To check or undo it:

orcraft-endpoint startup --status
orcraft-endpoint startup --remove

Registration uses each platform's own user-level mechanism, so it never asks for administrator or root rights, and the endpoint starts when you log in:

Windows - a Task Scheduler task. Nothing to install; Task Scheduler and PowerShell are part of Windows.
macOS - a launch agent in your own ~/Library/LaunchAgents that opens the endpoint in Terminal.app. Nothing to install.
Linux - a systemd user service that opens the endpoint in a terminal window in your desktop session. A standard desktop install already has everything it needs.

The one thing to know about Linux: because the endpoint is shown in a real terminal window, auto-start needs a graphical session and a terminal emulator on PATH - any of gnome-terminal, xfce4-terminal, konsole, kitty, alacritty or xterm. On a desktop image one of these is always present. On a minimal image, one package covers it:

sudo apt install xterm

On a headless Linux server with no desktop at all, skip auto-start and launch the endpoint the usual way - running it directly has no such requirement.

Troubleshooting

Endpoint status: Locked

If the endpoint shows as Locked, the endpoint application answers but a run cannot start there:

The license row of the card says which of these it is:

The localhost card reads Not signed in: sign in from the Account tab, as above.
Ready for license: the machine holds no valid license, or its license ran out while no controller was signed in to renew it. Right-click the card and choose Activate License.
No license slot: every machine slot of your plan is in use. Revoke the license of a machine you no longer need, or move to Team from the Account tab, then activate this one.

Endpoint status: Online

If the endpoint shows as Online instead of Ready, the controller can ping it, but the controller and endpoint applications are failing to connect to each other:

Possible causes:

A security mismatch: one side is running in secure mode and the other isn't.
Both sides are in secure mode, but the security setup procedure in the controller's Security tab was not completed as required.
A firewall is blocking the selected port on one of the machines - see Prerequisites/TCP port.
The port configured in the controller doesn't match the port the endpoint is listening on.
The endpoint process was stopped or restarted after the ping succeeded.
On Windows, the controller's machine still holds an address the endpoint machine no longer uses - see System reference/Stale name lookups.

Endpoint status: Offline

If the endpoint shows as Offline, the controller cannot even ping it: