Develop and troubleshoot a Scenario on your own machine

urthctl run executes a probe in the machine where the CLI runs. Use it to iterate on a new Scenario or investigate a failed Worker run. It uses the probe implementations available in that CLI build, with the local machine's network, credentials, permissions, and runtimes.

Local execution stays out of server history

A local run does not create a server Result or upload Artifacts. You cannot post its test results back to the API server with urthctl run. Only authorized Workers can report claimed executions using their run authority. This keeps development and troubleshooting output out of operational history. To obtain a recorded result, trigger a separate Worker run after testing.

Choose the machine before interpreting the result

Your local machine may not be able to reach the target. A laptop outside a private VPC can fail a probe that succeeds on a Worker inside it. DNS answers, VPN routes, proxies, target credentials, TLS trust, and browser dependencies can also differ.

Use a machine with the connectivity you intend to test. A jump host is a machine you can access through SSH that has a route to the target network. Running the CLI on that host tests from its network perspective. It does not automatically reproduce every property of the Worker environment.

Set the local deadline

Local execution uses --runner.timeout, which defaults to one minute. It does not currently use the Scenario manifest's prob.timeout. The HTTP examples set --runner.timeout=5s to match the Scenario. Set the intended deadline for your own test. Browser workflows can need a longer deadline.

Run a local manifest

Install urthctl and the dependencies for the probe kind. Use the manifest from Create test scenarios, or a file you already maintain. Create a private working directory:

install -d -m 700 ./worker
urthctl run -f scenario.yaml --runner.working-directory=./worker --runner.timeout=5s

A file-based run does not need an API login or a Worker enrollment token. Scenario placement labels and project Runner grants do not route this run: the CLI executes the probe directly on this machine.

Read the probe log and final script finished result. The CLI can print a failed probe result while returning zero to the shell in the current implementation. Do not use the process exit status alone to decide whether the probe passed.

Reproduce the saved server definition

To fetch and execute a Scenario by name, sign in and select the project:

urthctl auth login
urthctl context use PROJECT
install -d -m 700 ./worker
urthctl run service-http-lab --runner.working-directory=./worker --runner.timeout=5s

The commands assume the configured control plane at https://urth.example.org. See Override the control-plane address for a different deployment. Your user needs read access to that project's Scenario. The API supplies the definition; your CLI machine executes it. Fetching by name does not claim a queued job or upload the local result.

To keep a copy and edit it without changing the server:

urthctl get scenario service-http-lab -o yaml > scenario.yaml
urthctl run -f scenario.yaml --runner.working-directory=./worker --runner.timeout=5s

Edit the file between those commands if needed. This fetches the current Scenario definition. If the failed recorded run used an earlier version, compare its execution input with the current definition before claiming that you reproduced the same test.

Run from a jump host

Use a jump host you are authorized to access that can reach the target. Install urthctl and the required runtimes there. The CLI needs no inbound connection from Urth and no Worker enrollment token for a local file run.

Export the Scenario on your management machine, then prepare a private directory on the jump host:

urthctl get scenario service-http-lab -o yaml > scenario.yaml
ssh operator@jump.example.org 'install -d -m 700 ~/urth-debug ~/urth-debug/worker'
scp scenario.yaml operator@jump.example.org:urth-debug/scenario.yaml
ssh operator@jump.example.org

After signing in to the jump host, run:

cd ~/urth-debug
chmod 600 scenario.yaml
urthctl run -f scenario.yaml --runner.working-directory=./worker --runner.timeout=5s

Replace the SSH address with your host. Confirm its DNS, route, TLS trust, and target access before interpreting the outcome. Use your approved mechanism for any target credentials. Do not copy a Worker enrollment token or installation key to the jump host; neither is needed for this test.

This file-based workflow also works when the jump host cannot reach the Urth API, provided it can reach the target. If the jump host can reach the API, you can instead authenticate a CLI profile there and run a saved Scenario by name. That requires project read access but still produces no server history.

Remove transferred definitions and retained output when they are no longer needed, under your data retention policy. They can contain sensitive target information or credentials.

Inspect scripts and retained output

For a Puppeteer Scenario, retain its temporary work directory while debugging:

urthctl run -f scenario.yaml --runner.working-directory=./worker --runner.timeout=30s \
  --puppeteer.headless --runner.keep-temp

Use this example for a browser Scenario, not an HTTP-only definition. The CLI host needs the Node.js and browser setup. --runner.keep-temp keeps browser working files; it does not export every Artifact from every kind of local probe. The current CLI prints artifact names but does not provide a general command to save all returned artifact contents.

You can also run supported script files directly:

urthctl run -f requests.http --runner.working-directory=./worker --runner.timeout=5s
urthctl run -f workflow.js --runner.working-directory=./worker --runner.timeout=30s \
  --puppeteer.headless --runner.keep-temp

The CLI infers these kinds from .http/.rest, .js/.mjs, and .har files. A complete Scenario manifest carries its explicit probe kind and is preferable when you want to retain the same definition for Worker execution.

Diagnose the failure, then verify through a Worker

Observation	Check next
File cannot be read or parsed	File path, manifest structure, and probe-specific fields.
Probe kind is unavailable	CLI build and supported probe registry.
Name resolution fails	DNS configuration from this execution location.
Connection fails or times out	Route, firewall, proxy, target availability, and address family.
TLS verification fails	Target hostname, certificate chain, validity, and local trust.
HTTP assertion fails	Actual status or body versus the expectation in the Scenario.
Browser script cannot start	Local runtime, browser dependencies, permissions, and work directory.
Local and Worker results differ	Network location, Scenario version, credentials, runtimes, and Worker load.

After correcting the definition, apply it through your authorized user profile and trigger a new recorded run:

urthctl apply scenario.yaml
urthctl trigger service-http-lab
urthctl get results service-http-lab

Run these on the management machine if the jump host has no API access. Inspect the new Result's actual Runner and Worker. The recorded run provides evidence from that Worker location; the local troubleshooting run remains local.