JupyterHPC Agentic AI Environment

The JupyterHPC Agentic AI Environment is a containerized Linux desktop environment with a pre-installed suite of AI coding agents, accessible through JupyterHPC on the GWDG HPC cluster. It provides a full KDE Plasma desktop with tools like Claude Code, OpenCode, Hermes, and Odysseus, all pre-configured to use SAIA models hosted on GWDG infrastructure.

Why use the JupyterHPC Agentic AI Environment? The tools described on the Agentic Coding page can also be used on your local machine. The JupyterHPC Agentic AI Environment provides the same agentic coding capabilities but runs inside an Apptainer (Singularity) container on HPC compute nodes. This gives you a sandboxed, reproducible environment where the AI can read and edit your project files on the cluster filesystem, run terminal commands, and access the Internet, all from your browser, with no local installation required.

Overview

The JupyterHPC Agentic AI Environment is a Singularity/Apptainer Image Format (SIF) container built on Rocky Linux 8.10 with a KDE Plasma 5 desktop environment. It is spawned as a Slurm job through JupyterHPC and accessed via a web-based VNC client in your browser.

The container comes with five AI tools pre-installed, all configured to use SAIA as the LLM backend:

All tools share a single SAIA_API_KEY environment variable. Configure it once and every tool picks it up automatically.

Spawning the AI Desktop

1. Go to https://jupyter.hpc.gwdg.de and log in with your Academic Cloud account.
2. On the Server Options page, configure:
   • HPC Project: Select your project
   • HPC Type: Select AI Agents
   • AI Agents: Select KDE
   • HPC Device: Choose CPU
3. Click Start

Once the desktop loads, you will see desktop icons for each AI tool. Double-click any icon to launch the tool in a terminal or browser window.

Setting Your SAIA API Key

All AI tools in the container require a SAIA API key. You only need to set it once. It is shared across all tools.

Option 1: Desktop GUI (easiest)

After the KDE desktop loads, double-click the Setup SAIA API Key desktop icon. Enter your key in the dialog. It will be validated and applied to all tools immediately, with no logout required.

Option 2: Command Line (Before Spawning)

Set the API key in your HPC home directory before spawning the desktop.

Login via SSH to any login node. Then run:

sed -i '/SAIA_API_KEY/d' ~/.bash_profile
echo 'export SAIA_API_KEY="your-key-here"' >> ~/.bash_profile
echo 'export APPTAINERENV_SAIA_API_KEY="$SAIA_API_KEY"' >> ~/.bash_profile

The APPTAINERENV_ prefix forwards the variable into the container automatically at job submission time. Stop your current JupyterHPC server and spawn a new one for the key to take effect.

To verify the key is set correctly:

bash -l -c 'echo SAIA_API_KEY=\$SAIA_API_KEY'

AI Tools

Claude Code

Claude Code is Anthropic’s CLI coding agent. It reads your codebase, edits files, runs terminal commands, and completes multi-step coding tasks autonomously.

In the JupyterHPC Agentic AI Environment, Claude Code is bridged to SAIA via saiaclaudebridge, a lightweight FastAPI app that translates the Anthropic API format to the OpenAI-compatible format that SAIA uses.

Claude Code Model Mapping

Claude Code sends model names like claude-sonnet-4-20250514 which SAIA doesn’t recognize. The bridge automatically maps them to tool-calling-capable SAIA models:

Launching Claude Code

Double-click the Claude Code desktop icon, or run from a terminal:

claude

The bridge starts automatically if it’s not already running.

Claude Code ECC Skills

Claude Code ships with 278+ ECC skills deployed to ~/.claude/skills/. These are active by default. Type /skills in Claude Code to list them. To disable a skill, delete the skill from this folder ~/.claude/skills/.

OpenCode

OpenCode is an open-source, terminal-first AI coding agent. It generates code, modifies files, executes commands, and automates development tasks directly from the terminal.

In the JupyterHPC Agentic AI Environment, OpenCode is pre-configured with a SAIA plugin that automatically fetches the live model list from the SAIA API on every login. This means new SAIA models appear in OpenCode without any manual configuration.

Launching OpenCode

Double-click the OpenCode desktop icon, or run from a terminal:

opencode

OpenCode Modes

• Plan mode: Create structured plans for complex multi-step tasks
• Build mode: Execute approved plans, run automation, and build workflows

Press ⭾ Tab to toggle between Plan and Build modes.

OpenCode Basic Commands

For more information, see the OpenCode documentation.

Hermes Agent

Hermes is NousResearch’s multi-modal AI agent. It supports text, image, and audio inputs, and includes 73 bundled skills for tasks like web search, file operations, and code execution.

In the JupyterHPC Agentic AI Environment, Hermes is pre-configured with a SAIA custom provider. The config is automatically refreshed on every login to ensure the default model is always valid against the current SAIA model list.

Launching Hermes

Double-click the Hermes Agent desktop icon, or run from a terminal:

hermes

Hermes Configuration

Hermes config is stored in ~/.hermes/config.yaml. The default model is set to glm-4.7 and automatically updated if it becomes unavailable on SAIA.

To manually refresh the Hermes config with current SAIA models:

refresh-hermes-config.sh

Odysseus

Odysseus (under evaluation) is a self-hosted AI workspace with a web UI. This service is currently under evaluation and we may choose to discontinue it on a future date after evaluation is complete. It provides RAG (retrieval-augmented generation), vector search via ChromaDB, deep research with DuckDuckGo, speech-to-text via faster-whisper, and image generation via diffusers.

Odysseus runs as a local web server on port 7000 with a ChromaDB vector database on port 8100. Per-user data is stored in ~/.odysseus/.

Launching Odysseus

Double-click the Odysseus desktop icon, or run from a terminal:

odysseus-launcher.sh

This starts ChromaDB, launches the Odysseus server, and opens Firefox to http://localhost:7000.

Odysseus Features

• Chat: Multi-model conversations with SAIA models
• Deep Research: Web search via DuckDuckGo (no API key required) + RAG over your documents
• Vector Search: ChromaDB-backed semantic search over uploaded documents
• Speech-to-Text: Local transcription via faster-whisper
• Image Generation: Text-to-image via diffusers (requires GPU for reasonable speed)

ECC Skills Library

The container ships with 278+ skills from the ECC (Enterprise Claude Code) repository. These are deployed once per user on first login:

• Claude Code: All 278 skills deployed to ~/.claude/skills/ (active by default)
• OpenCode: Commands, prompts, tools, and plugins deployed to ~/.opencode/
• Hermes: ECC skill imports deployed to ~/.hermes/skills/

Skills are deployed with cp -n (no-clobber). If you delete a skill, it stays deleted. To restore a skill, copy it from the read-only originals inside the container:

cp -r /opt/claude-template/skills/<skill-name> ~/.claude/skills/<skill-name>

Model Selection

All AI tools in the container use SAIA models. You can select from the full list of locally available models.

For agentic coding workloads, we recommend:

Tool Calling Support

Claude Code and other agentic tools require models that support tool calling (function calling). The following SAIA models have been verified to support tool calling:

What Happens at Login

First Login (One-Time Setup)

A background process (non-blocking) runs on first login:

1. Installs Claude Code into ~/.local/ai-tools/ via npm
2. Deploys 278+ ECC skills to ~/.claude/skills/, ~/.opencode/, and ~/.hermes/skills/
3. Seeds Odysseus data directories in ~/.odysseus/ (ChromaDB, settings, features)
4. Creates Hermes config in ~/.hermes/config.yaml with SAIA provider
5. Deploys OpenCode SAIA plugin to ~/.config/opencode/plugins/
6. Copies desktop icons for all AI tools to ~/Desktop/
7. Auto-prompts for SAIA API key if not already set (GUI dialog)

A sentinel file (~/.cache/.kde-ai-first-login-done) prevents re-running the heavy setup on subsequent logins.

Security and Containment

The JupyterHPC Agentic AI Environment provides natural sandboxing for agentic AI tools through Apptainer container isolation:

• Read-only SIF: The container image is immutable. AI tools and system libraries cannot be modified at runtime.
• Filesystem isolation: The AI can only access what is mounted into the container (your HPC home directory).
• No root access: The container runs as your unprivileged HPC user. No root, no access to other users’ data.
• Network isolation: Outbound internet access is routed exclusively through the GWDG proxy, providing the same restrictions as any regular JupyterHPC user.
• Ephemeral sessions: When your Slurm job ends, the container is gone. A fresh spawn gives a clean environment. Your HPC home directory is mounted read-write, so the AI can read and edit your project files there. Session history, tool configs, and installed skills persist in your home directory across sessions.

Troubleshooting

Spawn Fails with Timeout

Check ~/current.jupyterhub.notebook.log on the login node for the actual error.

AI Tools Report no API Key

• Ensure SAIA_API_KEY is exported in ~/.bash_profile on the cluster (not just .bashrc).
• Or use the Setup SAIA API Key desktop icon to configure it interactively.

APIConnectionError or Connection Error

• The GWDG CA bundle (SSL_CERT_FILE) set by the job script can block external HTTPS.
• Auto-fixed: The login profile script unsets SSL_CERT_FILE. Log out and back in if you still see errors.

OpenCode or Claude Not Found in Terminal

• The tools are installed in ~/.local/ai-tools/bin/ and /usr/local/lib/hermes-agent/bin/.
• These are added to PATH via profile scripts. If missing, add to ~/.bashrc:

echo 'export PATH="$HOME/.local/ai-tools/bin:/usr/local/lib/hermes-agent/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Slurm Sbatch Socket Timed Out

This is a Slurm infrastructure issue, not a container problem. The Slurm controller was temporarily unreachable. Wait a few minutes and try spawning again. If it persists, contact hpc-support@gwdg.de.

Manually Starting AI Tools

If desktop icons don’t work, start tools from a terminal: