Getting Started with Artefacts
Creating an account
You will need an email address or a Google account. Then go to https://app.artefacts.com and proceed.
Recommended System Requirements for Running Robotic Application Tests
The Artefacts client is relatively lightweight and so any hardware requirements will be based on the simulation that is being attempted, rather than Artefacts itself.
We support what ROS2 supports, i.e:
- Ubuntu 22.04 (Recommended for ROS2 Humble projects)
- Ubuntu 24.04 (Recommended for ROS2 Jazzy projects)
On MacOS or Windows, we recommend using a virtual machine with Ubuntu 22.04 or 24.04.
Our general recommendations for running simulations are:
- minimum of 8G of RAM (depending on the complexity of the simulation)
- minimum of 4 CPU cores (depending on the complexity of the simulation and your robotic application)
- at least 20G of free disk space (to work with simulation assets, rosbags…)
CLI installation
Using Python version 3.10 or above:
pip install artefacts-cli
Isolated Installation (pipx, uv)
pipx and uv can directly expose the artefacts shell commands while keeping artefacts-cli installed in an isolated python environment.
pipx
Install pipx then:
pipx install artefacts-cli
uv
Install uv then:
uv tool install artefacts-cli
To expose ROS 2 libraries to the CLI, users might require the --python and --system-site-packages flags. For example pipx install artefacts-cli --python /usr/bin/python3 --system-site-packages.
Then the artefacts command is globally available.
Post‑install check
Run artefacts doctor to see a quick review of the range of Artefacts features that are immediately available.
The command confirms core functionalities, suggests optional recommended settings, and provides further information for Robotics frameworks users, like ROS in the next section.
Please check to CLI doctor reference for further information.
Doctor will recommend installing shell completion for a more comfortable experience using Artefacts:
artefacts completion install
This enables tab completion for the artefacts command in bash, zsh, and fish on Linux,
MacOS and experimental support for PowerShell on Windows.
See the completion command reference for more details.
ROS Users
In general, for Python virtual environment to work reliably with ROS, we recommend adding the virtual environment directly to the Python search path.
Example for a Python 3.10 environment created in /home/[USER]/<myproject>/venv:
export PYTHONPATH=$PYTHONPATH:/home/[USER]/<myproject>/venv/lib/python3.10/site-packages
For ROS 2 Jazzy Users (Ubuntu 24 and Python 3.12)
This distribution comes with stricter Python environment isolation.
Whenever you are using artefacts, we would strongly recommend adding the system Python packages directory to PYTHONPATH, in addition to your virtual environment (if using):
export PYTHONPATH=$PYTHONPATH:/usr/lib/python3/dist-packages
If you are running your tests in Docker using our jazzy base images (e.g., public.ecr.aws/artefacts/ros2:jazzy-harmonic), both the virtual environment and PYTHONPATH environment variable are already configured to work correctly with ROS2 Jazzy. This means pip-installed packages will be available even after sourcing ROS. No further Python environment configuration is required.
Usage reference
For CLI usage, refer to the CLI reference
For configuring the artefacts.yaml file, refer to the Configuration file syntax
Tutorials and example projects
For writing tests with ROS2, see the ros-2-simulation-workflows repository
Example projects:
- Minimal example: Example Turlesim
- Robot Navigation Nav2 + Gazebo demo
General Troubleshooting
We have a general troubleshooting section for working (specifically with testing) with ROS that we hope you may find useful while you are developing.