# Install OpenCode in the HPC cluster
This guide explains how to install OpenCode — an AI coding assistant that works in your terminal — on the HPC cluster, connected to the PCSS AI Models service (https://llm.hpc.psnc.pl).
The installation is done with a single ready-made script. It is already installed on the cluster — every user can run it with the command opencode-install. It is interactive, requires no administrator rights and installs everything inside your grant's project_data directory, not in your home directory, so your home quota stays untouched.
# 1. What you need before you start
| Requirement | Where to get it |
|---|---|
| HPC cluster account | HPC Getting Started (opens new window) |
| PCSS AI Models service activated (LLM access) | https://pcss.plcloud.pl (opens new window) — see the AI Portal Guide |
| PCSS API key | Portal → your LLM service → Service Parameters → API key (see section 3.11 of the AI introduction) |
| SSH access to the cluster login node | ssh your_login@ssh.hpc.pcss.pl |
Keep your API key secret
Your API key authorises all token usage on your account. Do not paste it into e-mails, tickets or shared files. The installer asks for it once and stores it in a private file (mode 600) that only you can read.
# 2. What the installer does
The opencode-install command (an installer script maintained by PCSS):
- Detects your grant directory (e.g.
~/pl1138-01) and itsproject_datafolder. If you have more than one grant, it shows a menu and asks where to install. - Removes any previous OpenCode installation (both old home-directory installs and installs inside
project_data), after your confirmation. - Installs the latest OpenCode (v2) from the official source — no root, no Node.js needed.
- Downloads the live list of PCSS models from the API and generates the configuration.
- Saves your API key in a private file and points the configuration at it, so the models work at once, on every start, without exporting anything.
- Adds the PCSS documentation MCP server — inside OpenCode you can search the PCSS docs directly (command
/mcps). - Adds one small PATH block to your
~/.bashrcso theopencodecommand works in every new terminal. - Verifies everything end-to-end (binary, config, key, MCP server, live model answer).
# Where everything is installed
Everything lives inside your grant's project_data directory:
<grant>/project_data/opencode/
├── .opencode/bin/opencode ← the OpenCode binary (~250 MB)
├── bin/opencode ← wrapper command (added to PATH)
├── config/opencode/ ← configuration + pcss.key (your API key)
├── data/opencode/ ← database, sessions, logs
├── cache/opencode/ ← cache
└── state/opencode/ ← state
In your home directory only a two-line PATH block is added to ~/.bashrc — nothing else. The home quota (1 GB) stays free for your files.
Several grant directories?
If your account has more than one grant directory, the installer lists them all with free space and lets you choose.
# 3. Step-by-step installation
# Step 1 — Run the installer
Log in to the cluster and run:
opencode-install
That's it — the installer is already on the cluster, you do not need to download anything.
Run it in an interactive SSH session on the login node (or inside an srun interactive session), not through sbatch.
The installer will:
- Show which grant directories it found and, if there are several, ask where to install — type the number and press Enter (just Enter = the first one).
- Ask for confirmation before removing an old installation — answer
YESto proceed with a clean install. - Ask for your PCSS API key — paste it and press Enter. While typing you will only see
xxxxxx— that is normal. - Verify the key on the PCSS server and finish the installation.
# Step 2 — Start OpenCode
Open a new terminal (or run source ~/.bashrc), then:
cd ~
opencode
Inside OpenCode:
| Command | Action |
|---|---|
/models | choose one of the PCSS models (e.g. pcss/GLM-5.3-Flash) |
/mcps | check the PCSS documentation MCP server |
/help | all commands |
The default model is pcss/GLM-5.3-Flash. The models are ready immediately — no export of any key is needed.
# 4. Installer options
| Command | What it does |
|---|---|
opencode-install | interactive install (asks for the key) |
opencode-install --yes | no confirmations (the key is still asked) |
opencode-install --dry-run | show what would be done, change nothing |
opencode-install --api-key 'sk-...' | install without typing the key interactively |
opencode-install --no-test | skip the live inference test at the end |
opencode-install --key-only | only replace the saved API key (no reinstall) |
opencode-install --keep-key | reinstall and reuse the saved key |
opencode-install --keep-existing | do NOT remove an existing installation |
opencode-install --uninstall | remove everything |
opencode-install --help | all options |
The installer always asks for the key
A key saved by an earlier run is never reused silently — you always know which key is in use. Only --keep-key reuses the stored key without a question. To change the key later (e.g. a new one from the administrator):
opencode-install --key-only
Do I need to download an OpenCode config file too?
No. The installer generates the configuration (opencode.jsonc) automatically:
- it downloads the live list of PCSS models from the API with your key, so the list always matches what your account really has,
- it writes the correct path to your saved key (inside
project_data, different for every user), - it writes the config in the format matching the installed OpenCode version.
A manually copied config file would quickly become outdated and would point at the wrong key path. If you ever need to inspect the generated file, it is at:
<grant>/project_data/opencode/config/opencode/opencode.jsonc
# 5. Updating and uninstalling
Reinstall / update to the newest OpenCode:
opencode-install
The installer is idempotent — you can run it as many times as you want. It removes the old installation and installs the newest version; your API key is asked again.
Remove everything:
opencode-install --uninstall
This removes the binary, the configuration, the saved key and the PATH block from ~/.bashrc.
# 6. More about OpenCode
- Official documentation: https://opencode.ai/docs (opens new window)
- PCSS models available in the service: see the AI introduction and the live list from the installer.
- The installation also configures the PCSS docs MCP server (
https://llm.hpc.psnc.pl/mcp) — inside OpenCode ask about the PCSS documentation and the assistant will search it for you.
# Models hosted in the PCSS AI Models service
The PCSS AI Models service (opens new window) hosts a wide range of open-source models, for example: GLM (GLM-5.3-Flash, GLM-5.2, GLM-5.1), DeepSeek (V3.1, V4), Qwen (Qwen3.5, Qwen3.8, Qwen3-VL), GPT-OSS 120B, Gemma, Mistral, MiniMax, MiMo and the Polish Bielik — plus image generation (Z-Image-Turbo), OCR (Nanonets-OCR), speech transcription (Whisper) and embedding/reranker models for RAG. OpenCode uses the chat models; the full, always-current list is available at https://llm.hpc.psnc.pl/ (opens new window) and via the /models command inside OpenCode.