Tutorial 1 Install

Tutorial index · 2. Scaffold a workspace →

---

Chapter 1 — Install the dev environment from .deb packages

Theia ships as a set of independent Debian packages under /opt/theia, the way ROS 2 ships under /opt/ros/<distro>. You install it on a fresh machine, source one script, and then work in your own workspace — without vendoring any of Theia into your repo.

1.1 The package set

There are four audiences; you pick the packages for the role you're playing. The cut follows one rule: a machine that only RUNS Theia gets binaries and nothing else; everything build-time lives in a matching -dev package.

Audience	Install	Gets
Run-only target (a board)	theia-runtime theia-services	supervisor + service binaries + libs. Zero build files.
App developer (you, now)	+ theia-framework theia-runtime-dev theia-services-dev	the above + the artheia CLI, runtime headers, protos, the .art tree, the Python manifest
Test author	+ theia-rf	the rf_theia Robot Framework harness
Operator	+ theia-tools (Ubuntu 24.04)	the supervisor-GUI + rtdb

The dependency DAG is clean and acyclic — theia-framework is the root, the -dev packages Depends: their run-only counterpart:

theia-framework  (artheia wheel + bazel rules + setup.sh; Architecture: all)
   ├─► theia-runtime         supervisor binary                  ← run
   │      └─► theia-runtime-dev   runtime src/hdrs + proto + .art    ← build
   ├─► theia-services        com/per/sm/ucm/log/shwa + libetcd   ← run
   │      └─► theia-services-dev  service protos + .art + py manifest ← build
   ├─► theia-tools           GUI + rtdb (need com's gRPC; 24.04) ← operate
   └─► theia-rf              rf_theia harness (Architecture: all) ← test

1.2 Where to get the .debs

If you have the Theia source checkout, you build the package set yourself with one verb (this is what a release engineer runs):

# from the theia checkout, with the workspace venv on PATH
PATH="$PWD/.venv/bin:$PATH" theia release            # → dist/debian/*.deb

theia release with no target runs the 4-step full build (framework → runtime → services → package) and drops the .debs under dist/debian/. Cross-arch builds:

theia release --arch host,rpi4       # amd64 + arm64 (bookworm)
theia release --arch jetson          # focal-arm64

Two verbs, two jobs. theia dist <target> builds debs from a serialized manifest (the runtime deb-set, or a per-machine app bundle); theia release <target> --s3 URL pushes the built runtime plane to S3. The no-target theia release above is the one-shot full-package build for cutting the dev environment — that's what you want here. See Chapter 5 for the deploy chain.

Otherwise your team publishes the .debs to an apt repo or a shared drive — get them from there.

1.3 Install — the app-developer set

You're the app developer, so install the framework + runtime + services + their -dev packages. dpkg/apt handle the ordering from the Depends: DAG. The .debs land under dist/debian/<pkg>/ (one subdir per package), so cd there and reference each by its subdir:

cd dist/debian        # or wherever your .deb files are
sudo apt install \
       ./theia-framework/theia-framework_*_all.deb \
       ./theia-runtime/theia-runtime_*_amd64.deb \
       ./theia-runtime-dev/theia-runtime-dev_*_amd64.deb \
       ./theia-services/theia-services_*_amd64.deb \
       ./theia-services-dev/theia-services-dev_*_amd64.deb \
       ./theia-system-dev/theia-system-dev_*_amd64.deb

The debs stage the framework under /opt/theia: the theia launcher + service/supervisor binaries in /opt/theia/bin, the bazel rules, and the artheia wheels under /opt/theia/wheels (Theia does not own your Python — it ships artheia as a wheel for you to install into your own venv, next).

1.4 Activate Theia — source setup.sh

Just like ROS 2's setup.bash, sourcing Theia's setup.sh puts the toolchain on your PATH and exports the environment your workspace needs. It is a single POSIX file — the same source line works from bash, zsh, or a plain sh:

source /opt/theia/setup.sh

This:

• prepends /opt/theia/bin (the theia launcher + the staged service/supervisor binaries) to PATH,
• exports THEIA_ROOT=/opt/theia (the framework prefix the toolchain resolves against).

It does not touch PYTHONPATH: artheia lives in your venv (next step), and the framework's services manifest is loaded by path from $THEIA_ROOT/ manifest/ — so nothing generic lands on your global import path.

Add the source line to your ~/.bashrc (or ~/.zshrc) so every new shell has Theia ready.

Working from a source checkout instead of the deb? The source tree ships the equivalent env.sh. From your workspace, source ../theia/env.sh does the same thing the deb's setup.sh does — plus it exports THEIA_TRACE_DECODER_PATH from the in-tree decoders. (The deb sets that per-workspace once you build your app's trace decoder; see Chapter 7.) Everywhere this tutorial says source /opt/theia/setup.sh, a source-checkout user reads source ../theia/env.sh.

1.5 Install artheia into your venv

Theia does not own your Python — the deb ships artheia (and the rf_theia harness) as wheels under /opt/theia/wheels. Create a venv in your workspace and install them from there:

python3 -m venv .venv && source .venv/bin/activate
pip install --find-links /opt/theia/wheels artheia rf-theia

--find-links /opt/theia/wheels resolves artheia + all its deps offline from the bundled wheels (no PyPI needed). Re-source /opt/theia/setup.sh if you opened this venv in a fresh shell. Keep this venv active whenever you run artheia/theia in the chapters that follow.

1.6 Verify the install

theia --help                 # the launcher resolves; lists the verbs
artheia --version            # the .art toolchain is in your venv
ls /opt/theia/bin            # theia + supervisor + com per sm ucm log shwa …

If theia --help prints a verb list and artheia --version prints a version, you're ready.

---

You now have: the Theia dev environment installed from .deb, setup.sh sourced, artheia installed into your venv, theia/artheia on your PATH.

Next: Chapter 2 — Start a new workspace, where you scaffold your own repo against this installed framework.

---

Tutorial index · 2. Scaffold a workspace →