# Getting Started with Artefacts

Site [llms.txt](/llms.txt)

---

## Creating an account

You will need an email address or a Google account. Then go to [https://app.artefacts.com](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:

```bash
pip install artefacts-cli
```

### Isolated Installation (pipx, uv)

[pipx](https://pipx.pypa.io/stable/) and [uv](https://docs.astral.sh/uv/) can directly expose the `artefacts` shell commands while keeping `artefacts-cli` installed in an isolated python environment.

#### pipx

[Install `pipx`](https://pipx.pypa.io/stable/installation/) then:

```bash
pipx install artefacts-cli
```

#### uv

[Install `uv`](https://docs.astral.sh/uv/getting-started/installation/) then:

```bash
uv tool install artefacts-cli
```

> [!NOTE] ROS users
> 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](/clireference/#doctor) for further information.

Doctor will recommend installing shell completion for a more comfortable experience using
Artefacts:

```bash
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](/clireference/#completion) for more details.

### Using a Python virtual environment for your project

`artefacts run` (without `--in-container`) executes your test command directly in the
current shell — it does **not** create, activate, or otherwise manage a Python environment
for you. If your project's own dependencies (test requirements, simulator bindings, etc.)
live in a virtual environment, activate it *before* calling `artefacts run`:

```bash
source venv/bin/activate
artefacts run my_job
```

> [!NOTE]
> `--in-container` mode doesn't have this concern: it builds and runs your job inside a
> Docker image built from your project's `Dockerfile`, which has its own self-contained
> Python environment regardless of what's active in your shell.

## 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`:

```bash
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):

```bash
export PYTHONPATH=$PYTHONPATH:/usr/lib/python3/dist-packages
```

> [!NOTE]
> 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](/clireference)

For configuring the `artefacts.yaml` file, refer to the [Configuration file syntax](/configuration/artefacts-yaml)

## Tutorials and example projects

For writing tests with ROS2, see the [ros-2-simulation-workflows repository](https://github.com/art-e-fact/ros2-simulation-workflows)

Example projects:

* Minimal example: [Example Turlesim](https://github.com/art-e-fact/example-turtlesim)
* Robot Navigation [Nav2 + Gazebo demo](https://github.com/art-e-fact/navigation2_ignition_gazebo_example)

## General Troubleshooting

We have a general [troubleshooting](/troubleshooting) section for working (specifically with testing) with ROS that we hope you may find useful while you are developing.