Getting started: zero to a working harness

This tutorial walks you all the way through your first Apothem setup. You start with nothing installed and finish with a real harness configuration — generated from a profile you wrote, verified, and confirmed working. Plan for about fifteen minutes. Every command below is real and copy-paste runnable.

By the end you will have:

1. Installed Apothem from the script installer.
2. Edited the shared profile that drives every harness.
3. Materialized a harness's native configuration.
4. Verified that configuration and confirmed a working first run.

We will use Claude Code as the example harness throughout, because it is the installer's default. The same steps apply to any supported harness — swap the name when you reach the harness list.

What you need firstCopy Anchor Link

• A Unix-like shell (macOS, Linux, or WSL). The PowerShell installer covers Windows; this tutorial shows the bash path.
• Python 3.10 or newer on your PATH. Check with python3 --version.
• The two runtime libraries the engine imports from your interpreter: click and rich. The rest of the stack (pyyaml, jsonschema) is vendored into the tree, so only these two need to be importable. If click or rich is missing, the installer stops and prints the install command. The one-line command pipes the script into bash, so it cannot prompt; set APOTHEM_AUTO_INSTALL_DEPS=1 (for example curl -fsSL https://apothem.ahmedgad.com/install.sh | APOTHEM_AUTO_INSTALL_DEPS=1 bash) or install the two packages first.

Apothem ships as a bundled source tree rather than a published package — there is no pip install step. The installer clones the tree and runs the engine directly from it.

Step 1 — Install ApothemCopy Anchor Link

Run the network installer:

curl -fsSL https://apothem.ahmedgad.com/install.sh | bash

The installer performs these steps:

1. Prerequisite check. The installer finds a real Python 3.10+ interpreter and confirms the two runtime libraries (click and rich) are importable. If one is missing it names it, stops, and prints the install command; set APOTHEM_AUTO_INSTALL_DEPS=1 to install without a prompt, since a piped run cannot prompt.
2. Source placement. The bundled tree is cloned into ~/.apothem (override with the APOTHEM_HOME environment variable). A re-run checks out the release tag in the existing clone instead of duplicating it.
3. Profile bootstrap. If you have no profile yet, the installer copies the example profile to ~/.config/apothem/profile.yaml, installs and verifies Claude Code from it in the same run, and warns that the identity fields are placeholders.

You can steer the install with environment variables. The ones you are most likely to use:

# Install a different user-scope harness and name the profile path explicitly.
# Put the variables on the `bash` side of the pipe: a variable placed before
# `curl` reaches only curl, not the installer.
curl -fsSL https://apothem.ahmedgad.com/install.sh | \
  APOTHEM_HARNESS=codex \
  APOTHEM_PROFILE="$HOME/.config/apothem/profile.yaml" \
  bash

The installer installs user-scope harnesses only. Install a project-scope harness afterward, naming the project:

apothem install --harness cursor --project /path/to/project

Other recognized variables are APOTHEM_REPO and APOTHEM_REF (which remote to clone and which git ref to check out — unset resolves and verifies the latest signed release tag; set a tag to pin it, or main for the moving branch (a branch is not a signed tag, so it also needs APOTHEM_ALLOW_UNVERIFIED=1)), APOTHEM_ALLOW_UNVERIFIED=1 (downgrade a tag-signature-verification failure to a warning, and allow a non-tag ref such as main), APOTHEM_SOURCE (use an existing local checkout instead of cloning), and APOTHEM_SKIP_VERIFY=1 (skip the post-install verify, which we want to run, so leave it unset).

When the installer finishes a full run it prints a banner showing how to invoke the engine. It places an apothem shim on your PATH (POSIX: $HOME/.local/bin; Windows: %LOCALAPPDATA%\Microsoft\WindowsApps), so once that directory is on PATH you run the engine directly:

apothem <command>

If the shim could not be placed — or its directory is not yet on PATH — the banner prints a self-contained fallback that needs no shim:

PYTHONPATH="$HOME/.apothem/src" python3 -m apothem <command>

The rest of this tutorial writes apothem <command>; if you are on the fallback form, prepend the exact prefix your installer banner printed.

Step 2 — Make the profile yoursCopy Anchor Link

The shared profile at ~/.config/apothem/profile.yaml is the single source of truth. Every harness adapter reads it and derives that harness's native config from it. Edit it once, and every harness you install stays consistent.

Open it in the engine's editor, or in any text editor:

apothem profile edit

A minimal, valid profile looks like this:

identity:
  name: "Example User"
preferences:
  style: "concise"
rules:
  - "Validate external input before writing files."

Replace the placeholder name with your own, and add any rules you want every harness to enforce. Keep example values fake — the profile is meant to be safe to share.

Confirm the engine reads your edits back cleanly:

apothem profile show --json

If the YAML is malformed, this is where you will see it — fix and re-run before moving on.

Step 3 — Materialize a harness configurationCopy Anchor Link

If your Step 1 run created the profile, it already installed Claude Code from the placeholder identity. Edit the profile in Step 2, then apply your identity with:

apothem update --harness claude-code

apothem install --harness claude-code

This reads your profile and writes Claude Code's native configuration. To see every harness you can target:

apothem harnesses list

Some harnesses are project-scoped rather than user-scoped, and those need a --project path so the adapter knows where to write:

apothem install --harness cursor --project .

Step 4 — Verify and confirm a first runCopy Anchor Link

Materializing is only half the story. Now confirm the configuration landed correctly:

apothem verify --harness claude-code

verify checks that the harness's managed config files exist and parse. Add --profile PATH and it also fails when an installed file has drifted from what that profile would produce. A clean run means the materialization succeeded.

For a whole-machine health check across every registered adapter, run:

apothem doctor

doctor checks every installed harness (it must verify, and its registered hook commands must start) and exits non-zero if any check fails. Harnesses you have not installed are listed but do not fail it, so it is a useful gate in a setup script.

Your first run. Open the harness you just configured — Claude Code, in our example — and start a session in any project. The rules and preferences you wrote into the profile are now part of that tool's behavior. That is the working first run: the profile you edited in Step 2 is shaping a real session.

What you builtCopy Anchor Link

Starting from an empty machine, you installed Apothem, authored a shared profile, materialized a harness's native configuration from it, verified the result, and confirmed it working. The profile is the durable artifact — change it once and re-run apothem update --harness <name> to push the change to any harness.

Where to nextCopy Anchor Link

• Add another tool. The harness list covers every supported platform and its adapter name. Repeat Step 3 with a new --harness.
• Go deeper on a single task. The how-to recipes cover adding a harness, editing the profile, and driving the installer. The usage guides cover writing rules, authoring plans, and running the conformity gate.
• Look up specifics. The reference documents each artifact class and the profile schema, and the CLI reference covers every command. Each adapter has its own page under harnesses.
• Plan work that outlives a session. Resumable planning explains how Apothem externalizes long-running work to a project-local .apothem/plans/ suite so a fresh session on any machine resumes it in place.

Recommended Next StepCopy Anchor Link

Run apothem doctor to check your setup — it reports the state of every registered adapter, so the harness you just installed shows as healthy while the rest show as not-yet-installed — before you move on to adding more harnesses.