Service Enabled Science at ALCF

Demo materials for ALCF Service-Enabled Science Workshop

Start Here

setup.sh installs uv, the Python environment for the exercises, opencode, and Claude Code, then configures opencode for the ALCF Inference Service:

./setup.sh

The same .venv also runs Session 05's MCP servers, so setup.sh finishes by checking those import cleanly.

Activate your virtual environment:

source .venv/bin/activate

If something goes wrong, please see the "Alternative Environment Setups" section below.

ALCF Tokens

To gain access to services covered in this hackathon, we recommend using alcf-tokens. After just one interactive login step, this CLI tool automatically refreshes and retrieves Globus access tokens for the following services:

Service	service-name
ALCF Inference Service	inference
ALCF IRI API	iri
Globus Compute	globus-compute
Globus Transfer	globus-transfer
Globus Flows	globus-flows

Authentication

To properly gain access to all ALCF services, make sure you authenticate with your ALCF credentials.

alcf-tokens login --authorize-transfer home --authorize-transfer eagle

The above command will print a URL that you can copy-paste to your browser. Select the Argonne LCF identity provider and enter your ALCF credentials. Copy-paste the authorization code back in your terminal.

Test your token:

alcf-tokens test-token inference

If successful, you should see

{"ready": true, "error": null}

Troubleshooting

If you have issues with your tokens, please logout from Globus by visiting https://app.globus.org/logout, open a new incognito browser, and restart a new authentication flow.

Coding Agents

Run ./setup.sh for the quick setup above, or install and configure the agents manually.

Install the agents:

curl -fsSL https://opencode.ai/install | bash   # opencode
curl -fsSL https://claude.ai/install.sh | bash  # Claude Code

The Inference Endpoints guide also covers Codex, pi, and other harnesses.

After authenticating, configure opencode:

uvx alcf-ai agent configure opencode

Configuring Claude Code is optional and works the same way:

uvx alcf-ai agent configure claude

The commands write the service endpoints and an API key to ~/.config/opencode/opencode.jsonc and ~/.claude/settings.json. Re-run them to refresh the key.

Note: alcf-ai v0.16.0 and earlier overwrote an existing agent config whenever it failed to parse, silently discarding your settings. Fixed in v0.17.0: configure now leaves an unreadable config untouched and saves a <name>.bak.<timestamp> backup before changing a file. Run uvx alcf-ai@latest ... to pick up the fix.

Alternative Environment Setups

You will need a Python 3.10+ environment with the alcf-tokens and alcf-ai packages installed.

We recommend one of the following methods.

Option 1: uv

uv is useful, as it can quickly bootstrap missing Python versions and manage per-tool environments:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv python install 3.12

uv venv --python 3.12 .venv
source .venv/bin/activate
uv pip install -r requirements.txt

Option 2: venv

This assumes you already have a Python3.10+ installation:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Option 3: conda

This assumes you have an Anaconda distribution installed, such as Miniconda:

conda create -n alcf-ses python=3.12 -y
conda activate alcf-ses
pip install -r requirements.txt

Automatic tool environments with uv

Beyond manually-managed virtual environments, uv can manage tool-scoped virtual environments which is often convenient:

# Install CLI tools with self-contained venvs:
uv tool install alcf-tokens
uv tool install alcf-ai

alcf-tokens --help

# If you'd rather not add tools to your PATH:
uvx alcf-tokens --help

You can remove installed tools with uv tool uninstall.

More on alcf-tokens

With a terminal, you can obtain access tokens with:

inference_token=$(alcf-tokens get-token inference)
iri_token=$(alcf-tokens get-token iri)
globus_compute_token=$(alcf-tokens get-token globus-compute)
globus_transfer_token=$(alcf-tokens get-token globus-transfer)

With python, you can obtain them with:

from alcf_tokens.auth import get_access_token, ServiceName

inference_token = get_access_token(ServiceName.inference)
iri_token = get_access_token(ServiceName.iri)
globus_compute_token = get_access_token(ServiceName.globus_compute)
globus_transfer_token = get_access_token(ServiceName.globus_transfer)