For Teachers & Admins

When a student submits an assignment that contains a grade.sh script, the following environment variables are available inside the grading environment.

Tested against Vocareum Notebook, VS Code, and JupyterLab. ✓ = present, ✗ = not present.

Variable reference

Grade and report outputs

Variable	Description	Vocareum Notebook	VS Code	Jupyter Lab
`$vocareumGradeFile`	Path to the grade output file. Write one `Criterion Name,Score` line per rubric criterion. Vocareum reads this file after `grade.sh` exits and records the scores.	✓	✓	✓
`$vocareumReportFile`	Path to the report output file. Write free-form text or HTML here; Vocareum displays it to the student as feedback. To suppress raw script stdout/stderr from appearing in the report, write `VOC_NO_REPORT_OUTPUT` as the first line.	✓	✓	✓

Working directory

Variable	Description	Vocareum Notebook	VS Code	Jupyter Lab
`$VOC_HOME_DIR`	Path to the student's working directory (`/voc/work`). Student-submitted files are copied here before `grade.sh` runs. Use this variable rather than a hardcoded path so your script works correctly across lab types.	✓	✓	✓
`$VOC_WORKAREA`	Host-side mount path for the student's working area (e.g., `/mnt/worktest/grader/.../work`). This is the underlying path on the grading server; use `$VOC_HOME_DIR` for reading student files instead.	✗	✓	✓

Assignment and course identifiers

Variable	Description	Vocareum Notebook	VS Code	Jupyter Lab
`$VOC_COURSEID`	Vocareum course ID.	✓	✓	✓
`$VOC_ASSIGNMENTID`	Vocareum assignment ID.	✓	✓	✓
`$VOC_PARTID`	Vocareum part ID.	✓	✓	✓
`$VOC_PARTVERSION`	The version of the part the learner selected, for assignments with multiple versions.	✓	✓	✓
`$VOC_SUBMISSION_COUNT`	Number of times this student has submitted this part.	✓	✓	✓

User identifiers

Variable	Description	Vocareum Notebook	VS Code	Jupyter Lab
`$VOC_USERID`	Vocareum user ID of the submitting student.	✓	✓	✓
`$VOC_USER_EMAIL`	Email address of the submitting student.	✓	✓	✓
`$VOC_EMAIL_ID`	Internal Vocareum email identifier.	✓	✓	✓

Jupyter environment

These variables relate to the Jupyter runtime configuration and are not typically needed in grading scripts.

Variable	Description	Vocareum Notebook	VS Code	Jupyter Lab
`$VOC_JUPYTER_IDE_TYPE`	The Jupyter IDE type (e.g., `lab`).	✓	✗	✓
`$VOC_JUPYTER_PREF_DIR`	Jupyter's preferred directory (`/home/labsuser`). Note: this is not the student working directory — student files are at `$VOC_HOME_DIR`.	✓	✗	✓
`$VOC_JUPYTER_ROOT_DIR`	Root directory for the Jupyter file browser (`/`).	✓	✗	✓
`$VOC_JUPYTER_USERNAME`	Username for the Jupyter session (`labsuser`).	✓	✗	✓
`$VOC_KERNEL_APP`	Jupyter kernel application (e.g., `jupyter kernelgateway`).	✓	✗	✓
`$VOC_KERNEL_BASE_URL`	Base URL for the Jupyter kernel.	✓	✗	✓
`$VOC_KERNEL_PORT`	Port the Jupyter kernel listens on.	✓	✗	✓

Other

Variable	Description	Vocareum Notebook	VS Code	Jupyter Lab
`$VOC_CURRENT_GRADE`	The student's current recorded grade for this part before this submission is processed.	✓	✓	✓
`$VOC_CUSTOM_DATA_FILE`	Filename for passing custom data between Vocareum components.	✓	✓	✓
`$VOC_IPC_DATA_FILE`	Filename used for inter-process communication within the grading pipeline.	✓	✓	✓
`$VOC_RESOURCE_TAGS`	Base64-encoded JSON blob containing course, part, and user identifiers. Not typically needed in grading scripts.	✓	✓	✓

GenAI variables

When GenAI is enabled for your course, additional environment variables are injected for AI model access. See the Environment Variables section of GenAI in Vocareum Labs for the full list and setup instructions.

Accessing variables in scripts

Example of accessing and printing environment variables from the grade.sh file (bash):

echo "Working dir: $VOC_HOME_DIR" 
echo "Submission count: $VOC_SUBMISSION_COUNT"

Note that if you would prefer to create the grading script in a different programming language, you can do so in a separate file. Just be sure to call your separate script from the grade.sh file.

Example of accessing and printing environment variables in a grade.py file (Python):

import os  
work_dir = os.environ.get("VOC_HOME_DIR", "/voc/work") 
submission_num = os.environ.get("VOC_SUBMISSION_COUNT", "1")

print(work_dir)
print(submission_num)

Grading Environment Variables