Codex

Codex je asistent na programovanie využívajúci umelú inteligenciu od spoločnosti OpenAI. Umožňuje kontrolovať a upravovať súbory, spúšťať príkazy a pracovať s existujúcim zdrojovým kódom z terminálu.

V infraštruktúre SAV sa Codex spúšťa v kontajneri Singularity/Apptainer na prihlasovacom uzle HPC. Pripája sa priamo k službám OpenAI; nevyžaduje server vLLM ani tunel SSH.

Rýchly štart

V adresári svojho projektu spustite:

cd ~/my-project
~/llm/codex.sh

Spúšťací skript zobrazí ponuku:

Relácia Codex:

  1) Obnoviť poslednú reláciu
  2) Spustiť novú reláciu
  3) Vybrať predchádzajúcu reláciu
  4) Ukončiť

Vyberte [1]:

Stlačením klávesu Enter obnovíte poslednú reláciu. Prípadne vyberte inú možnosť.

Spúšťací skript

Nižšie uvedený skript uložte ako ~/llm/codex.sh a nastavte mu právo na spustenie:

chmod +x ~/llm/codex.sh

Na rozpoznanie UID a skupiny používateľa v kontajneri skript využíva dva súbory s údajmi o účte z hostiteľského systému. Vytvorte ich jednorazovo:

mkdir -p ~/llm
getent passwd root "$USER" > ~/llm/.container_passwd
getent group root "$(id -gn)" > ~/llm/.container_group

Ak sa zmenia údaje vášho účtu alebo primárna skupina, súbory vytvorte znova. Skript nespúšťajte ako používateľ root, pokiaľ nechcete zámerne použiť jeho autentifikáciu a históriu relácií.

Autentifikácia

Codex sa pripája k službám OpenAI. Prihláste sa spôsobom podporovaným vašou inštaláciou a účtom, spravidla spustením Codexu a vykonaním pokynov na prihlásenie. Skript pripája adresár $HOME, takže konfigurácia a údaje o reláciách zostávajú zachované medzi spusteniami. Lokálny API kľúč pre vLLM nie je potrebný.

Používanie

codex.sh [WORKSPACE] [MODE] [-B HOST[:CONTAINER]] [-- CODEX_ARGS...]

  WORKSPACE    Pracovný adresár (predvolene aktuálny adresár)
  MODE         --continue, --new, --resume alebo --list
  -B, --bind   Ďalšie pripojenie adresára (možno opakovať)
  -- ARGS      Ďalšie argumenty odovzdané Codexu

Príklady:

# Otvorenie ponuky v aktuálnom adresári.
~/llm/codex.sh

# Práca v inom adresári a spustenie novej relácie.
~/llm/codex.sh /myproject/path --new

# Obnovenie poslednej relácie.
~/llm/codex.sh --continue

# Otvorenie výberu relácií.
~/llm/codex.sh --resume

# Pripojenie ďalších adresárov.
~/llm/codex.sh /myproject/path \
    -B /project/<account_ID>:/project/<account_ID> \
    -B /scratch/<account_ID>:/scratch/<account_ID>

# Zobrazenie pomocníka Codex CLI.
~/llm/codex.sh --new -- --help

Režimy relácií

Režim skriptu	Argumenty Codexu	Účinok
--continue	--no-daemon resume --last	Obnovenie poslednej relácie
--new	--no-daemon	Spustenie novej relácie
--resume	--no-daemon resume	Otvorenie výberu relácií
--list	--no-daemon resume	Alternatíva na otvorenie výberu relácií
(none)	Interaktívna ponuka	Výber režimu

--continue a --resume sú voľby spúšťacieho skriptu, nie priame voľby Codexu. Codex na obnovenie relácií používa podpríkaz resume. Voľba --no-daemon sa používa preto, že niektoré kontajnerové inštalácie neobsahujú kompletný balík servera na pozadí. Ak sa vaša verzia správa inak, skontrolujte codex --help a codex resume --help.

Funkcia spúšťacieho skriptu

Skript kontroluje obraz kontajnera a pracovný adresár, spracúva voľby relácií a ďalšie pripojené adresáre, podľa potreby načíta Singularity a spustí Codex so zvolenými argumentmi. Cestu k obrazu kontajnera a ku konfigurácii Slurmu možno nastaviť bez úpravy skriptu.

~/llm/codex.sh

#!/bin/bash
set -euo pipefail

# ----------------------------------------------------------------------
# Configuration
# ----------------------------------------------------------------------

CODEX_SIF="${CODEX_SIF:-/apps/images/vllm/x86_64/Codex_x86_64_Nov2026_perun.sif}"

if [[ -z "$CODEX_SIF" || ! -f "$CODEX_SIF" ]]; then
    echo "ERROR: CODEX_SIF is not set or the image does not exist." >&2
    echo "Example: export CODEX_SIF=/path/to/Codex.sif" >&2
    exit 1
fi

USER_HOME="$HOME"
USER_LLM_DIR="$HOME/llm"

WORKSPACE="$PWD"
WORKSPACE_SET=0
MODE=""

EXTRA_ARGS=()
EXTRA_BINDS=()

# ----------------------------------------------------------------------
# Usage
# ----------------------------------------------------------------------

usage() {
    cat <<EOF
Usage:
  $(basename "$0") [WORKSPACE] [MODE] [OPTIONS] [-- CODEX_ARGS...]

Modes:
  --continue       Continue the last session
  --new            Start a new session
  --resume         Select a previous session
  --list           Open the session picker

Options:
  -B, --bind HOST[:CONTAINER]
                   Add an additional bind mount (repeatable)
  -h, --help       Show this help

Examples:
  $(basename "$0")
  $(basename "$0") /project/myproject
  $(basename "$0") --continue
  $(basename "$0") /project/myproject --new
  $(basename "$0") -B /data:/data
  $(basename "$0") /project/myproject -B /data:/data -- --model gpt-5.1-codex

Default bind mounts:
  \$HOME:\$HOME
  /project/p2075-26-2:/project/p2075-26-2
  /run/munge:/run/munge
  /var/spool/slurmd/conf-cache:/etc/slurm
  \$HOME/llm/.container_passwd:/etc/passwd
  \$HOME/llm/.container_group:/etc/group
EOF
}

# ----------------------------------------------------------------------
# Parse arguments
# ----------------------------------------------------------------------

while [[ $# -gt 0 ]]; do
    case "$1" in
        --continue|--new|--resume|--list)
            MODE="$1"
            shift
            ;;

        -B|--bind)
            if [[ $# -lt 2 ]]; then
                echo "ERROR: $1 requires a bind specification." >&2
                exit 1
            fi

            EXTRA_BINDS+=("$2")
            shift 2
            ;;

        --)
            shift
            EXTRA_ARGS+=("$@")
            break
            ;;

        -h|--help)
            usage
            exit 0
            ;;

        -*)
            echo "ERROR: Unknown option: $1" >&2
            usage >&2
            exit 1
            ;;

        *)
            if [[ "$WORKSPACE_SET" -eq 0 ]]; then
                WORKSPACE="$1"
                WORKSPACE_SET=1
            else
                echo "ERROR: Unexpected argument: $1" >&2
                usage >&2
                exit 1
            fi
            shift
            ;;
    esac
done

# ----------------------------------------------------------------------
# Validate workspace
# ----------------------------------------------------------------------

WORKSPACE="$(realpath "$WORKSPACE")"

if [[ ! -d "$WORKSPACE" ]]; then
    echo "ERROR: Workspace does not exist: $WORKSPACE" >&2
    exit 1
fi

# ----------------------------------------------------------------------
# Interactive session menu
# ----------------------------------------------------------------------

case "$MODE" in
    --continue)
        CODEX_ARGS=(--no-daemon resume --last)
        ;;

    --new)
        CODEX_ARGS=(--no-daemon)
        ;;

    --resume|--list)
        CODEX_ARGS=(--no-daemon resume)
        ;;

    "")
        if [[ ! -t 0 ]]; then
            echo "Not a terminal. Pass --continue, --new," >&2
            echo "--resume or --list explicitly." >&2
            exit 1
        fi

        echo
        echo "Codex session:"
        echo
        echo "  1) Continue last session"
        echo "  2) Start new session"
        echo "  3) Select previous session"
        echo "  4) List sessions"
        echo "  5) Exit"
        echo

        read -r -p "Select [1]: " CHOICE || CHOICE=1

        # Pressing Enter selects the default.
        CHOICE=${CHOICE:-1}

        case "$CHOICE" in
            1)
                CODEX_ARGS=(--no-daemon resume --last)
                ;;
            2)
                CODEX_ARGS=(--no-daemon)
                ;;
            3|4)
                CODEX_ARGS=(--no-daemon resume)
                ;;
            5)
                exit 0
                ;;
            *)
                echo "Invalid selection." >&2
                exit 1
                ;;
        esac
        ;;

    *)
        echo "Unknown option: $MODE" >&2
        usage >&2
        exit 1
        ;;
esac

# Append additional Codex arguments.
CODEX_ARGS+=("${EXTRA_ARGS[@]}")

# ----------------------------------------------------------------------
# Default bind mounts
# ----------------------------------------------------------------------

BINDS=(
    "$WORKSPACE:$WORKSPACE"
    "$USER_HOME:$USER_HOME"
    "/project/p2075-26-2:/project/p2075-26-2"
    "/run/munge:/run/munge"
    "/var/spool/slurmd/conf-cache:/etc/slurm"
    "$USER_LLM_DIR/.container_passwd:/etc/passwd"
    "$USER_LLM_DIR/.container_group:/etc/group"
)

# Append user-defined bind mounts.
for bind in "${EXTRA_BINDS[@]}"; do
    BINDS+=("$bind")
done

# ----------------------------------------------------------------------
# Load Singularity
# ----------------------------------------------------------------------

if command -v module >/dev/null 2>&1; then
    module load singularity
fi

if ! command -v singularity >/dev/null 2>&1; then
    echo "ERROR: singularity command not found." >&2
    exit 1
fi

# Check architecture.
if [[ "$(uname -m)" != "x86_64" ]]; then
    echo "ERROR: This Codex image requires x86_64." >&2
    exit 1
fi

# ----------------------------------------------------------------------
# Build bind arguments
# ----------------------------------------------------------------------

SINGULARITY_BINDS=()

for bind in "${BINDS[@]}"; do
    SINGULARITY_BINDS+=(--bind "$bind")
done

# ----------------------------------------------------------------------
# Launch Codex
# ----------------------------------------------------------------------

singularity exec \
    "${SINGULARITY_BINDS[@]}" \
    --pwd "$WORKSPACE" \
    --env "PATH=/usr/local/bin:/opt/agent_env/bin:/opt/slurm/bin:/opt/slurm/sbin:$HOME/.local/bin:/usr/bin:/bin" \
    "$CODEX_SIF" \
    bash -lc 'exec codex "$@"' -- "${CODEX_ARGS[@]}"

Pripojenie SLURM na clustri Devana

Na clustri Devana je potrebné pripojiť SLURM nasledovne -- bind /etc/slurm:/etc/slurm & --env "PATH=/usr/local/bin:/opt/agent_env/bin:$HOME/.local/bin:/usr/bin:/bin"

Zodpovedné používanie agentov

Codex môže spúšťať príkazy a upravovať súbory. Príkazy spustené priamo agentom sa vykonávajú na prihlasovacom, nie výpočtovom uzle. Výpočtovo náročné kompilácie, testy a simulácie preto spúšťajte prostredníctvom Slurmu.

Agentovi môžete napríklad zadať:

Skompiluj softvér a spusti jeho testy. Kompiláciu a testy odošli cez Slurm
do CPU partície s použitím príslušného projektového účtu. Skontroluj stav
úlohy a oznám výsledok.

Čerpanie výpočtovej alokácie

Codex môže odosielať úlohy, ktoré čerpajú výpočtovú alokáciu vášho projektu. Zadajte projektový účet, partíciu, požadované zdroje a časový limit. Bežiace úlohy kontrolujte príkazom squeue -u "$USER".

Úpravy súborov

Codex vykonáva skutočné zmeny súborov. Pracujte v správnom projektovom adresári, používajte správu verzií a pred potvrdením zmien alebo spustením vygenerovaného kódu skontrolujte vykonané úpravy.

Pripojenie adresárov

Skript pripája pracovný a domovský adresár. Ak sú dostupné, pripája aj prostriedky Munge a Slurmu a voliteľné súbory s údajmi o používateľovi.

Pripojenie	Účel
$WORKSPACE:$WORKSPACE	Prístup k projektovému adresáru
$HOME:$HOME	Trvalé uloženie autentifikácie, konfigurácie a relácií
/run/munge:/run/munge	Adresár autentifikačného socketu Munge
$SLURM_CONF_DIR:/etc/slurm	Konfigurácia klienta Slurm
.container_passwd:/etc/passwd	Rozpoznanie používateľského účtu hostiteľa
.container_group:/etc/group	Rozpoznanie skupiny hostiteľa

Ďalšie adresáre možno pripojiť opakovaným použitím voľby -B:

~/llm/codex.sh /myproject/path \
    -B /project/<account_ID>:/project/<account_ID> \
    -B /scratch/<account_ID>:/scratch/<account_ID>

Zdrojové cesty musia na hostiteľskom systéme existovať a byť prístupné. Pripojenie pracovného adresára automaticky nesprístupní ostatné adresáre mimo neho.

Riešenie problémov

Obraz kontajnera Codex sa nenašiel

Skontrolujte nastavenú cestu:

printf '%s\n' "$CODEX_SIF"
ls -lh "$CODEX_SIF"

Ak CODEX_SIF nie je nastavená, nastavte cestu k obrazu podľa postupu vyššie.

unexpected argument '--continue' found

--continue nie je priamou voľbou Codexu. Použite voľbu spúšťacieho skriptu --continue, ktorá sa prevedie na codex --no-daemon resume --last. Voľbu --continue neposielajte priamo spustiteľnému súboru Codexu.

this CLI has no complete local package

Niektoré kontajnerové obrazy obsahujú CLI, ktoré nedokáže spustiť server na pozadí. Nainštalovaná verzia môže odporučiť voľbu --no-daemon. Skript ju používa pri nových aj obnovených reláciách. Ak problém pretrváva, skontrolujte inštaláciu alebo vytvorte nový obraz s kompletným CLI.

Skontrolujte nainštalované rozhranie príkazového riadka:

apptainer exec "$CODEX_SIF" codex --help
apptainer exec "$CODEX_SIF" codex resume --help

codex: command not found

Skontrolujte spustiteľný súbor v kontajneri:

apptainer exec "$CODEX_SIF" sh -c 'command -v codex'

Ak sa spustiteľný súbor nachádza inde, upravte premennú PATH v kontajneri alebo záverečný príkaz spúšťacieho skriptu.

Príkazy Slurmu v kontajneri nefungujú

Skontrolujte dostupné prostriedky na hostiteľskom systéme:

ls -ld /run/munge "$SLURM_CONF_DIR"
ls -l ~/llm/.container_passwd ~/llm/.container_group

Overte, že klient Slurmu je dostupný v kontajneri:

apptainer exec \
    --bind /run/munge:/run/munge \
    --bind "$SLURM_CONF_DIR:/etc/slurm" \
    --env 'PATH=/opt/slurm/bin:/opt/slurm/sbin:/usr/bin:/bin' \
    "$CODEX_SIF" squeue -u "$USER"

Príznak	Možná príčina
squeue: command not found	Spustiteľné súbory Slurmu nie sú v PATH
Neplatný používateľ/skupina	Chýbajúce alebo neaktuálne súbory s údajmi o účte
Chyba autentifikácie Munge	Socket Munge nie je dostupný alebo pripojený
Nemožno kontaktovať riadiaci uzol	Nesprávna konfigurácia Slurmu alebo problém so spojením
Chyba pripojenia adresára	Zdrojová cesta neexistuje alebo nie je prístupná

Codex nemá prístup k projektovým súborom

Skontrolujte prístupové práva a ďalšie cesty pripojte pomocou -B:

ls -ld "$PWD"
~/llm/codex.sh "$PWD" -B /project/shared:/project/shared

Reláciu nemožno obnoviť

História relácií je uložená v domovskom adresári používateľa. Použite rovnaký unixový účet a domovský adresár ako pri vytvorení relácie. Na výber predchádzajúcej relácie spustite:

~/llm/codex.sh --resume

Relácia vytvorená bežným používateľom nemusí byť viditeľná pri spustení skriptu ako root.

Prehľad príkazov a nastavení

Úloha	Príkaz
Interaktívna ponuka	~/llm/codex.sh
Obnoviť poslednú reláciu	~/llm/codex.sh --continue
Spustiť novú reláciu	~/llm/codex.sh --new
Vybrať predchádzajúcu reláciu	~/llm/codex.sh --resume
Alternatívny príkaz na výber relácie	~/llm/codex.sh --list
Iný pracovný adresár	~/llm/codex.sh ~/my-project
Pripojiť ďalší adresár	~/llm/codex.sh -B /data:/data
Pomocník Codexu	~/llm/codex.sh --new -- --help

Premenná	Účel
CODEX_SIF	Cesta k obrazu Singularity s Codexom
SLURM_CONF_DIR	Adresár konfigurácie Slurmu na hostiteľovi

Odkazy

• Codex
• Dokumentácia Codex CLI
• Dokumentácia SingularityCE

Created by: Marek Štekláč