Skip to main content

Artemis Runner

A runner enables you to validate your code by running builds, tests, and benchmarks on your own machine. The Artemis Runner is a single self-contained binary that you download, configure, and run to connect your hardware to the Artemis platform — letting you run code outside the platform safely and efficiently.

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.

Setting up a new runner: from a project's Runner and Scripts, "Set up a new runner" takes you to Platform Settings, Runners, where you click "New Artemis runner"

Method 1: Via Platform Settings​

  1. Click Platform Settings in the header bar
  2. Go to the Runners section under Integrations in the left sidebar
  3. Click "New Artemis runner" to generate a registration token

Method 2: Via Project Settings​

  1. Navigate to your project's Settings tab in the top navigation
  2. Go to the Runner and Scripts section in the left sidebar
  3. Click "Set up a new runner" under the Runner dropdown — this 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 (Python 3.11 + pip). On the New Artemis runner screen, choose your OS (Linux, Windows, or macOS) and architecture; 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.

Add new Artemis runner setup panel

  1. Create a folder and download the runner binary

    Windows (PowerShell):

    New-Item -ItemType Directory artemis-runner; Set-Location artemis-runner
    iwr -Uri "https://files.artemis.turintech.ai/public/artemis-runner/artemis-runner-5.2.0-windows.exe" -OutFile "artemis-runner.exe"

    Linux (bash):

    mkdir artemis-runner && cd artemis-runner
    curl -L "https://files.artemis.turintech.ai/public/artemis-runner/artemis-runner-5.2.0-linux" -o artemis-runner && chmod +x artemis-runner

    Copy the exact command for your platform from the setup panel — it fills in the current version, OS, and architecture for you.

  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

    Once it connects, your runner appears in the Active Runners list and becomes selectable in the project's Runner and Scripts dropdown.

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. Command triggered — User runs a validation command on the Artemis web platform
  2. Runner receives command — Your local runner picks up the command from the channel
  3. Repository copied locally — Runner clones your repository to a temporary folder (see Task output: where your code is downloaded and run to learn where, and how to change it)
  4. Command executed — Runner executes the command on the local copy
  5. Logs sent back — Real-time logs stream back to the Artemis server

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 automatically from that URL — no separate microservice configuration is required.

./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 advanced usage scenarios for the Artemis runner, including running multiple runners, resource management, proxy configuration, 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.

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 clones each candidate version of your code into a subfolder of its worker output root — your system's cache directory by default — executes your build, test, and benchmark commands there, and streams the results back to the Artemis platform.

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 — a larger disk, a faster drive, or simply a folder that's 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.

Keeping built versions (Delete Mutated)​

This setting applies to Code Optimization runs. Delete Mutated controls whether built versions are archived once they finish: with it set to Yes, a version's build/ folder is copied into the mutated/ folder; with No, the build/ folder is simply deleted. To change it:

  1. Run ./artemis-runner configure
  2. Choose Edit Advanced Options
  3. Select Delete Mutated and answer No
note

Delete Task Output and Delete Mutated are independent: the first decides whether the whole task folder survives, the second decides whether built versions are kept inside it.

Reusing build artefacts (Incremental Build)​

This setting applies to batch validations. When Incremental Build is set to Yes, build artefacts from an earlier validation in the same batch run are reused by later validations, which can speed the run up; with No, each validation builds from scratch. Code Optimization always builds incrementally, regardless of this setting. To change it:

  1. Run ./artemis-runner configure
  2. Choose Edit Advanced Options
  3. Select Incremental Build and answer Yes

What's inside a task folder​

Each task gets its own folder, named task-{task_id}, inside the worker output root. The layout inside depends on which Artemis feature triggered the task. There are three main variations:

Code validation​

Used for most activity on the Optimise page (other than Code Optimization): single and batch code validation, Artemis Intelligence, Spec Coder, and testing your commands from the Settings page.

task-{task_id}/
├── input/
│   └── {project_id}/          # your code, as downloaded
└── output/
    ├── original_repo/         # pristine working copy
    ├── build/                 # validated version — kept after the run (the last one, for batch validation)
    └── build_dir_backup/      # baseline with build artefacts (only when incremental builds are enabled)

Code Optimization​

Used for multi-target Code Optimization runs.

task-{task_id}/
├── input/
│   └── {project_id}/          # your code, as downloaded
└── output/
    ├── original_repo/         # pristine working copy (baseline)
    ├── build/                 # version currently being built (not kept — see note below)
    ├── mutated/               # archived built versions — inspect these after a run
    │   ├── 0/                 # baseline (trial 0)
    │   └── {version_number}/  # one folder per candidate version
    └── build_dir_backup/      # baseline with build artefacts (only when incremental builds are enabled)

When you evaluate a single version from Code Optimization, the layout is the same except archived versions are stored under mutated/{test_id}/.

Changesets and Discover​

Used for changeset evaluation. Discover uses changesets under the hood, so its tasks look the same.

task-{task_id}/
├── input/
│   └── {project_id}/          # current state of changeset, as downloaded
└── output/
    └── build/                 # build environment (copy of changeset code, kept after the run)
What happens to the build/ folder

The build/ folder is where commands are actually executed against a candidate version. What happens to it when a run finishes depends on the feature:

  • Code validation and Changesets / Discover: the build/ folder is preserved. For batch validation it holds the contents of the last version validated.
  • Code Optimization: the build/ folder is ephemeral. Whether a built version is kept is governed by Delete Mutated — use the mutated/ folders to inspect built versions after a run.

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 — regenerate it if it has
  5. Review SSL certificate configuration if using HTTPS
Last updated on by Paul Brookes