Skip to main content

Artemis Runner

A Runner lets Artemis verify your code by running your Scripts (builds, tests and benchmarks) on a machine you choose. The Artemis Runner is software you download, configure and start on your workstation or server. It receives tasks, runs a downloaded copy of the Project's saved code, and sends logs and results back to Artemis.

Registered, online and selected are separate conditions: a Runner has to be registered with your deployment, running so it is online, and selected for the Project or the workflow you are running.

Accessing Runner Setup​

There are two ways to reach the runner setup screen, where you generate the download command and a single-use registration token.

Method 1: Via Platform Settings​

  1. Click Platform Settings in the sidebar
  2. Open Runners in the Integrations group
  3. Click New Artemis runner to generate a registration token

Method 2: Via Project Settings​

  1. Open Project Settings in the Project sidebar
  2. Open Runner and Scripts
  3. Click Add new Artemis runner under the Runner dropdown. It takes you to the Runners screen above, where you click New Artemis runner

Quickstart​

On Linux and Windows the Runner ships as a single self-contained binary. On macOS it installs from a Python wheels archive into a Python 3.11 virtual environment. On the New Artemis runner screen, choose your OS (Linux, Windows or macOS) and architecture, and the panel generates the exact download command and a single-use registration token. Use a bash shell on macOS/Linux, or PowerShell 5.0+ on Windows. See the downloads page for direct links and the macOS install steps.

  1. Create a folder and download the runner binary

    Windows (PowerShell):

    New-Item -ItemType Directory artemis-runner; Set-Location artemis-runner
    Invoke-WebRequest -UseBasicParsing -Uri 'https://files.artemis.turintech.ai/public/artemis-runner/artemis-runner-latest-windows.exe' -OutFile 'artemis-runner.exe'

    Linux (bash):

    mkdir artemis-runner && cd artemis-runner
    curl --fail --location 'https://files.artemis.turintech.ai/public/artemis-runner/artemis-runner-latest-linux' --output 'artemis-runner' && chmod +x artemis-runner

    Copy the exact command for your platform from the setup panel. It fills in the right OS and architecture for your deployment.

  2. Configure the runner

    Pass the deployment URL and the single-use token from the setup panel. Optionally add --runner-name to skip the interactive name prompt.

    .\artemis-runner.exe configure --url https://artemis.turintech.ai --token <YOUR_TOKEN> --runner-name "my-runner"

    On Linux/macOS, invoke it as ./artemis-runner configure ....

  3. Start the runner

    .\artemis-runner.exe start

    The setup page checks the status automatically and shows New runner detected once it connects. The Runner then appears in the Runners list and can be selected in the Project's Runner and Scripts dropdown, in a Branch Validation, or in Discovery setup.

note

The registration token is single-use and time-limited. If it expires or is already spent, click Regenerate on the setup panel (or create a new runner) to get a fresh one.

Registering with an API key​

The token flow above is what the Web UI setup panel generates. A runner can equally register itself on first start using your Artemis API key, which avoids the Web UI round-trip entirely and is usually the better fit for scripted or agent-driven setup:

set -a; . ~/.config/artemis/.env; set +a   # exports ARTEMIS_API_KEY
./artemis-runner start \
  --runner-name "my-runner" \
  --url https://artemis.turintech.ai \
  --no-delete-task-output

Upgrading the runner​

To update an existing runner to the latest release, run:

artemis-runner upgrade

How the Runner Works​

Runner architecture

The runner operates through a secure REST API communication:

  1. Task queued: you run a Script from a Branch's Scripts tab, or a Discovery Run executes a Version.
  2. Runner picks it up: the selected Runner receives the task from Artemis.
  3. Code downloaded: the Runner downloads a copy of the saved code into a task folder. It is not a Git clone, and it does not include uncommitted edits from your own checkout. See Task output for where it goes.
  4. Commands executed: the Script's setup, benchmark and teardown commands run on that copy.
  5. Results sent back: logs and metrics stream back to Artemis.

Configuration Options​

Running configure saves your settings to a settings.env file next to the binary. When you start the runner, values are resolved in this order: CLI flags > environment variables > settings.env > defaults, so you can override any saved setting on the command line without re-running configure.

On-premise deployments​

For on-premise Artemis, pass your deployment's base URL with --url when configuring. All service connection variables are derived from that URL, so no separate service configuration is needed.

./artemis-runner configure --url https://artemis.internal.company.com --token <YOUR_TOKEN>

SSL Configuration​

Configure SSL certificate verification with the --ssl-verify flag or the ARTEMIS_SSL_VERIFY environment variable:

export ARTEMIS_SSL_VERIFY=true    # Use system CA certificates (default)
export ARTEMIS_SSL_VERIFY=false   # Disable SSL verification
export ARTEMIS_SSL_VERIFY=/path/to/ca/certificates.pem  # Custom CA certificates

Usage Tips​

  • Ensure your runner has adequate disk space for project dependencies
  • Keep the start process running. The Runner is only online while it is running
  • Use meaningful runner names to identify them in the platform
  • Monitor runner logs to troubleshoot any connection issues

Advanced Usage

This section covers running several Runners, resource limits, proxies, and where your code is downloaded and run.

Running multiple runners​

You can run more than one runner at the same time. Runners that share a name form a pool: when a task comes in, Artemis sends it to any available runner in that pool. You have no control over which one is picked, so every runner in a pool should be interchangeable: same code, same environment, same toolchain.

To scale out, just start several runners with the same name. Tasks are distributed across whichever ones are free.

To create a separate pool, start a runner under a different name. Only one runner name is stored in the settings file, so pass --runner-name to override it:

./artemis-runner start --runner-name "my-runner-name"

Runners with different names appear as separate options on the platform and never share tasks.

Several runners in one Discovery Run​

Several runners on different machines can be attached to the same Discovery Run, so the same versions are measured on each machine and you can compare them across hardware. Give each machine its own runner name when the hardware differs, because Artemis treats runners in a pool as interchangeable.

Resource Management​

Limiting RAM Usage​

You can control the amount of RAM available to your evaluations using the --ram-limit-mb flag or the ARTEMIS_RAM_LIMIT_MB environment variable. This is particularly useful on systems with limited resources or when you need consistent resource usage across environments.

# Set RAM limit to 4GB (4096MB) via flag
./artemis-runner start --ram-limit-mb 4096

# Or via environment variable
export ARTEMIS_RAM_LIMIT_MB=4096
./artemis-runner start
note

The RAM limit is specified in megabytes (MB). For example:

  • 1GB = 1024MB
  • 2GB = 2048MB
  • 4GB = 4096MB
  • 8GB = 8192MB
warning

Setting the RAM limit too low may cause evaluations to fail if they require more memory than allocated. Monitor your evaluations' memory usage to determine appropriate limits.

Proxy Configuration​

If you're experiencing connection issues in a corporate environment with a proxy, configure no_proxy to allow direct connections to your Artemis deployment.

Environment Variables​

  • no_proxy/NO_PROXY: Comma-separated list of hosts to bypass the proxy

Troubleshooting Connection Issues​

For SaaS Artemis (artemis.turintech.ai)​

export no_proxy=localhost,127.0.0.1,artemis.turintech.ai
./artemis-runner start

Direct connections to Artemis can be faster and more reliable than going through a corporate proxy.

For On-premise Artemis​

# For domain-based deployment
export no_proxy=localhost,127.0.0.1,artemis.internal.company.com

# For IP-based deployment
export no_proxy=localhost,127.0.0.1,192.168.41.1

./artemis-runner start

Testing Connectivity​

Before starting the runner, verify connectivity:

# Test direct connection (with no_proxy)
curl -v https://artemis.turintech.ai

# Test internal deployment
curl -v https://artemis.internal.company.com

Diagnosing proxy issues​

  1. Verify no_proxy is set correctly

    echo $no_proxy

  2. Check if the proxy is blocking Artemis. SSL certificate errors may indicate proxy SSL inspection; connection timeouts may indicate proxy blocking

Task output: where your code is downloaded and run​

When a task runs, the Runner downloads the Version of your code into a subfolder of its worker output root, which is your system's cache directory by default (typically ~/.cache/artemis-runner on Linux). It runs your commands there and streams the results back to Artemis. Each command starts in that copy (output/build) in its own shell. Write artemis_results.json or artemis_results.csv there or in a folder below it.

The exact path is printed in the runner output at the start of each run. If you ever need to locate files or debug a failure, check there first. See What's inside a task folder for the layout.

Two advanced options control this behaviour: Worker Output Root (where the files go) and Delete Task Output (whether files are kept after a run). To change either:

  1. Run ./artemis-runner configure
  2. Choose Edit Advanced Options
  3. Select the option you want to change

Changing where tasks run (Worker Output Root)​

By default, the runner works inside your system's cache directory. If you'd rather have tasks run somewhere else, such as a larger disk, a faster drive or a folder that is easier to find, set a custom location:

  1. Run ./artemis-runner configure
  2. Choose Edit Advanced Options
  3. Select Worker Output Root and enter the directory you want the runner to use

All subsequent tasks will be downloaded and executed under that directory.

Keeping files after a run (Delete Task Output)​

By default, the runner deletes a task's folder as soon as the task completes, so old runs don't fill up your disk. If you want to keep the files for inspection, for example to look at build artefacts or dig into a failing test, turn this off:

  1. Run ./artemis-runner configure
  2. Choose Edit Advanced Options
  3. Select Delete Task Output and answer No
Watch your disk space

With Delete Task Output set to No, every run leaves its files behind, including a full copy of your repository per task. Clear out old task folders from the worker output root periodically.

Output options on the command line​

The same settings are available as artemis-runner start options and environment variables. Command-line flags win over environment variables, which win over settings.env.

PurposeStart optionEnvironment variable
Keep task folders--no-delete-task-outputARTEMIS_DELETE_TASK_OUTPUT=false
Choose the output root--worker-output-root /absolute/pathARTEMIS_WORKER_OUTPUT_ROOT
Keep the last N local task logs--task-log-retention-limit NARTEMIS_TASK_LOG_RETENTION_LIMIT

Local task-<id>.log files rotate separately and 10 are kept by default. Keeping task folders does not stop log rotation, and nothing can recover files that your own teardown commands deleted. The logs and metrics already sent to Artemis are kept either way.

The configure menu also lists Delete Mutated and Incremental Build. They apply only to the legacy Code Optimization workflow and do not affect Branch Script runs or Discovery Runs.

What's inside a task folder​

Each task gets its own folder, named task-{task_id}, inside the worker output root. For Branch Script runs and Discovery Runs it looks like this:

task-{task_id}/
├── input/
│   └── {project_id}/          # the saved code, as downloaded
└── output/
    └── build/                 # where the commands run

The task folder is cleaned when a task starts and normally removed when it ends, unless Delete Task Output is off. Do not rely on files surviving from one Validation to the next.

Next Steps​

Once your runner is configured and running, you can:

Troubleshooting​

If you encounter connection issues:

  1. Verify your saved settings in settings.env (re-run configure if needed)
  2. Check your internet connection
  3. Confirm the runner name is unique on your account
  4. Make sure your registration token hasn't expired, and regenerate it if it has
  5. Review SSL certificate configuration if using HTTPS
Last updated on by Eoin