PacePaper teacher guide

This step-by-step guide covers the current PacePaper classroom demo. PacePaper runs on one teacher computer. Students use a browser to connect to that computer through the school network. Start with the guide supplied with your app download; an older download may not include features described in a newer guide.

PacePaper is for practice and candidate familiarisation only. It does not deliver an official examination. A fresh installation starts with one preloaded Sample paper that has no subject, level, or IB branding, so you can try the whole exam workflow before building your own. An older app download does not update itself; use the guide supplied with your version.

The four parts of the teacher dashboard

Use the left-hand menu to move between these areas:

Area	What it is for
Overview	Confirm classroom sharing is on, copy the student address, and check that PacePaper is connected.
Classes	Create classes, add students, import class lists, and set extra time.
Sessions	Give a paper to a class, open its clock, start the exam, watch candidate work live, and review submissions.
Paper library	Choose an included example, build a paper, import a saved paper, or preview one as a student.

A paper is reusable exam content. A session is one sitting of that paper with one class. You can use the same paper again without rebuilding it.

Select User guide in the teacher sidebar to open these instructions in another tab. The guide also works offline from the HTML file supplied with the app.

Marking stays with the teacher: a packaged installation includes no worked answers and no marking guides, and candidate copies never carry them.

Quick classroom checklist

Follow this order for a complete practice exam:

Start PacePaper and sign in as the teacher.
Check the Student sign-in address shown under Classroom sharing in Overview (PacePaper shares the classroom network by default; choose a different address there if the network changed).
Copy the Student sign-in address and test it on one student device. The bare address is enough: opening it goes straight to candidate sign-in.
In Classes, create or import the class and check every student's details.
In Paper library, choose an included example or create/import a paper. Use Preview as student to see exactly what candidates will see before the lesson.
In Sessions, choose the class, exam system, and paper, then select Set up exam.
Open that session's clock on the second screen.
Ask students to sign in, select the exam, and wait.
Check that the correct students are present.
Select Start exam. Reading time begins now, when applicable.
Monitor online and submitted counts while students work.
After submission, open View submissions and select Print or save PDF.

The detailed instructions below follow the same order.

Step 1 — Start PacePaper

PacePaper is a portable app, not an installer. Extract the complete download before opening it.

Computer	Download	Open
Apple-silicon or Intel Mac	Use the source option below	`Start PacePaper.command`
Windows x64	`windows-x64.zip`	`PacePaper.exe`
Linux x64	`linux-x64.tar.gz`	`PacePaper`

Download the latest release bundle for Windows or Linux from the project's releases page. There is no Mac app bundle; on a Mac, install Bun and follow Run from a source checkout below, with IT help for the one-time setup.

Open PacePaper once on the teacher computer.
Leave the application running for the whole lesson.
Wait for the teacher dashboard to open in the normal browser.
Sign in with username admin and password admin.

Change the password any time in Settings — the current password is required, the new one must be at least 10 characters, changing it signs every teacher device out, and it persists with your data.

The teacher dashboard and the candidate screens offer a Light/Dark theme toggle (teacher topbar; student waiting-room and exam toolbars). Teacher and student choices are remembered separately per device, and both start on the system setting.

The local address usually looks like http://127.0.0.1:9148/admin. It may use a port from 9148 to 9158 if another program is already using the first one.

Do not open public/index.html or any file:// address. Run only one copy of PacePaper at a time.

Run from a source checkout

This option needs Bun installed on the teacher computer. If it is not already installed, ask your IT support to install Bun and run bun install once in the PacePaper project folder.

On a Mac:

Open the PacePaper project folder.
Double-click Start PacePaper.command.
Leave the Terminal window open.
Use the teacher page that opens automatically.
When completely finished, press Control-C in the Terminal window to stop PacePaper.

On Windows or Linux, open a terminal in the project folder and run bun run start:app. Keep the terminal open and press Control-C there when finished. This also works on a Mac.

Use the page that opens automatically. This launcher includes the example library and the Classroom sharing controls described below.

Step 2 — Let students connect

PacePaper shares the classroom network from launch, using the address it saved last time (the first private network address is chosen and saved on a new installation).

Select Overview.
Find Classroom sharing.
Check the private network used by the teacher and student devices, and choose another detected address if needed.
Select Apply classroom sharing.
Find the Student sign-in address.
Select Copy URL.
Open that exact address on one real student device.
Confirm that the PacePaper student sign-in page appears.

Do this test before students begin. localhost and 127.0.0.1 work only on the teacher computer.

The Student sign-in address on the dashboard and on the examination clock is always the private-network address that student devices open — it never shows 127.0.0.1 or localhost, and students can type it without adding /student because the bare address opens candidate sign-in. If classroom sharing is off, the examination clock still shows the network address but warns that students cannot connect until sharing is applied.

The teacher and students must be on a network that allows their devices to communicate. Guest Wi-Fi, different school networks, or network isolation may block access.

Classroom sharing cannot be changed while any examination is live. Do not quit or restart PacePaper during an exam.

Step 3 — Prepare the class

Select Classes. Add students one at a time or import a prepared CSV class list.

Option A — Add students manually

Under Create class, enter a clear Class name.
Enter a short Class code using at least four letters, numbers, or hyphens.
Select Create class.
Under Add student, select the class.
Enter the student's Student name and Candidate code.
Enter Extra time in minutes, or leave it at 0.
Select Add student.
Repeat for the rest of the class.
Check the class list before moving on.

Select Edit beside a student to change their name, candidate code, or extra time. Select Save changes when finished.

Option B — Import a class list

Select Download blank template.
Open the CSV file in Excel, Numbers, or Google Sheets.
Add one row for each student.
Repeat the class name and class code on every student row.
Enter 0 in extra_minutes when a student has no extra time.
Save or download the completed sheet as a CSV file.
Back in PacePaper, choose the file under Class-list CSV.
Select Import class list.
Check the displayed classes and students.

One CSV file may contain several classes. To create an empty class, include one row with the three student fields left blank.

Class codes and candidate codes identify existing records. Importing the same file again updates matching names and extra time and adds missing students. It does not remove students. Restore a removed class or student before importing a row with the same code.

Select Export active classes to save the current active rosters as CSV. Store exported files securely because they contain student names.

Check before starting

Add or edit every candidate before selecting Start exam. PacePaper creates the candidate responses from the active class list when the exam starts. Students added afterwards are not added to that live sitting. Avoid changing extra time during a live exam.

Step 4 — Choose or create the paper

Select Paper library, the final dashboard section. A fresh standalone installation includes one preloaded Sample paper:

Sample paper — three original texts with short-answer and multiple-choice questions across a reading period, showing the main question styles and the student reader experience. It carries no subject, level, or IB branding.

You can build or import other papers for your own approved practice materials. An installation with past sessions may also show papers labelled earlier demo version. Choose the current version for a new session; the earlier one remains available with its previous work.

Use an included paper

The only paper a fresh installation includes is the Sample paper above. For approved practice material, build a paper in the Paper Builder below, or import a prepared PacePaper paper file.

If your installation also shows development example papers — a source checkout may seed them — choose an Exam system to narrow the list, use Find a paper, and read the full title, paper number, and level or tier. Use the chosen paper when setting up the session in Step 5.

Read the label in each title before using an example:

Full-length mock provides a complete original question workload with the researched timing and mark allocation. Review the questions before use.
Full-format practice identifies an IB-oriented example following the researched paper structure, timing, and allocated marks. The questions still need a subject teacher's review for suitability and difficulty.
Format rehearsal demonstrates the type of paper and still needs subject-language review.
Walkthrough uses short timings to demonstrate section changes, breaks, and submission in a few minutes.

Full-length does not mean official or difficulty-calibrated. No awarding body has approved these papers, and no official grade boundaries are supplied. Have your subject team check the questions, materials, difficulty, and marking before using a mock with a class.

Build a new paper

Find Paper Builder in the Paper library area.
Under Choose the exact exam format, select the Exam system. The builder currently offers IB Diploma Programme, IB MYP eAssessment, Cambridge IGCSE Mathematics 0580, Pearson Edexcel International GCSE Mathematics A, selected 2027 AP formats, and a school-custom practice option.
Select the assessment session or profile year.
Select the course, syllabus, or qualification.
Select the level or tier when the chosen system uses one.
Select the exact paper, component, or delivery format.
Read the practice profile, timing facts, tool rules, and teacher guidance that appear.
Check the Practice paper title and Paper name.
Check the Reading time, Writing time, and Maximum marks.
Add clear Student instructions.
Add the first question under Questions and student entry areas.
Enter the complete question wording and its marks.
Choose one of the response areas offered for that exam format.
Attach any image, PDF, or audio required only for that question.
Repeat for the remaining questions.
Scroll through Paper preview and check the full student view.
Confirm that the marks a student can earn match Maximum marks. For a choose-one paper, count the selected question rather than adding all alternatives together.
Select Save paper to library.
Confirm that the paper appears in the Paper library with the correct exam-system name.

Choose the exam type before entering questions. If you change format, PacePaper asks first and keeps the old paper as a recoverable draft in this browser, including attachments. Select Recover an unfinished paper, choose the draft, then Restore draft. Undo question removal restores the last removed question and its attachments.

Wait for Draft saved in this browser before closing the page. Drafts belong to this browser and this PacePaper address; they are not in the shared paper library or a database backup. Use Save paper to library, then export the paper, when you want to keep or move it. If draft storage fails, keep the page open and save to the library; format changes and sign-out are blocked to protect the draft.

For papers with fixed timed sections, the reading and total-time fields are read-only. Editing the instructions, title or marks keeps the sections and breaks intact. Choose a custom format if you need a different schedule.

The selected profile changes the terminology, timing, marks, materials, suggested question cards, available response areas, delivery description, phase plan, and tool guidance. For an AP paper, assign every question to the correct section or part using the field shown on its question card. PacePaper then locks earlier sections, blocks entry during explicitly locked phases and the monitored break, and changes the displayed calculator/material rule for each part. AP English's optional 15-minute reading period remains inside its writable 135-minute free-response phase; it is not a separate lock.

The AP profiles target May 2027 and remain visibly marked Adapted practice. PacePaper currently uses one fixed classroom break timer that advances automatically; the official digital application waits for each candidate to select Resume Testing after the break timer. AP hybrid free-response practice should use a physical response booklet when closest format rehearsal is required. PacePaper does not include an exam calculator: supply the type shown for that paper and section. Check the current official course guide, specification, and session instructions before a full mock exam.

Add paper materials

Add paper-wide PDFs, source text, or listening audio under Details and student materials.
When building your own paper, attach any reference document required by the selected preset, such as a mathematics formula sheet or the AP Biology equations and formulas sheet.
For any paper you use — including a development example, when present — read Before you start and supply any further permitted calculator, equipment, or materials listed there.
Add an image, PDF, or audio file to an individual question when only that question needs it.
Enter the complete question wording in Question or prompt. Attached PDF pages are not copied into the printed candidate response automatically.
Images appear with the response when printed. PDFs and audio are listed as companion material.
Listening audio allows two complete listens. Students cannot pause, restart, seek, or change speed after a listen begins.
For a canvas question, choose its starting page count and default background: Blank, Ruled, or Square grid.
Students can draw, erase, undo, redo, add pages, and change the background. PacePaper warns them before changing the teacher's default.

Preview a paper as a student

Before a lesson, check what candidates will actually see rather than reading the paper's settings:

Open Paper library.
Find the paper and select Preview as student. The candidate interface opens in a new tab.
Work through the paper as a candidate would: change question, use the tools, play the audio, and print nothing.
Close the tab when you have seen enough.

The preview uses the real candidate interface with the paper's own timings, so reading time, phase changes, and locked sections behave exactly as they will in the sitting. Nothing is recorded: answers are not saved, final submission does nothing, audio listens are not counted, and no class, session, or response is created. Clearing a preview sitting therefore needs no cleanup. The preview belongs to your teacher session, so it opens only while you are signed in to the dashboard.

Export or import a paper

To move a teacher-created paper to another PacePaper installation:

Find the paper in the library.
Select Export to save one .digitaldp-paper file.
On the other installation, open Paper library.
Under Import a saved paper, choose the file.
Select Import paper.
Confirm that it appears in the Paper library.

The paper file contains its questions, settings, and permitted attachments. It does not contain classes, students, exam sessions, or responses.

Step 5 — Set up the exam session

Select Sessions.

Under Set up an exam, choose the Class.
Choose the Exam system.
Choose the Paper. Only papers from the chosen system are shown.
Read Before you start. Check the number of question cards, marks, timing, instructions, and any calculator or materials requirements.
Select Set up exam.
Find the new session in the list.
Confirm that it says Ready to start.

Setting up a session does not start its clock. It only makes the exam available for that class to choose and wait for.

One question card may contain several parts. Check the questions, timing, and marks before students join.

You may set up several sessions in advance. Different classes can take different exams at the same time. One class can have only one live session at a time.

Step 6 — Open the examination clock

Find the correct session.
Select its Open clock ↗ link.
Move the new tab or window to the projector or second screen.
Check the paper, class, start time, reading time, and writing time.
Edit the displayed student names if needed.
Confirm that the student sign-in address is visible.

For a simple paper with one reading period and one writing period (no fixed timed sections), changing Reading minutes or Writing minutes and selecting Save exam timing and update display saves the configured minutes for that sitting. For example, 0.1 reading minutes is six seconds. You can make this change while the exam is ready or after it has started: saving during a live exam moves the reading/writing boundary and the deadline immediately for every candidate, which is the fastest way to correct a mistaken duration. Check the saved confirmation and the session's timing on the teacher dashboard.

The display title, details and student-name list stay local to that clock window. Linked clocks always follow the saved exam start, duration and sections, including changes saved in another window. The start date is read-only; Start exam on the teacher dashboard controls the start. An exam that has ended can no longer change its saved timing.

Fixed timed sections stay read-only. If the paper uses a fixed multi-phase schedule of sections and breaks, the clock's timing fields are disabled; use the Paper Builder to prepare a paper with a different schedule. Candidate-specific extra time remains separate from the standard room clock.

If another window changes the timing while you are editing, saving shows a conflict message. Select Reload exam defaults, review the updated times, then make your change again. A temporary Custom countdown is separate from student exams and is not saved after refresh.

For simultaneous exams, open the clock from each specific session row. A clock opened without a chosen session prefers an ongoing exam, so always check its paper and class before projecting it.

The clock remains on Ready to start until the teacher selects Start exam. Reading time does not count down while students are joining.

Step 7 — Ask students to join

Give students the Student sign-in address and the class code.

Ask each student to:

Open the exact address supplied by the teacher.
Enter the Class code.
Select Load names.
Choose their own name.
Select Continue.
Under Choose your examination, find the correct paper.
Select Join waiting room.
Check the paper title and wait for the teacher.

Their sign-in screen and waiting room both state that the teacher can see their work during the sitting: answers, drawings, notes, and flagged questions, within PacePaper only.

Ask students to confirm that the correct paper title appears in their waiting room. In Classes, connected students should show as online.

Step 8 — Start and monitor the exam

Return to the correct session on the teacher dashboard.
Check the class and paper title one last time.
Select Start exam.
Confirm that the clock changes from ready to reading or writing time.
For a sectioned paper, confirm that the clock shows the current section, permitted tools, next transition, and full room schedule.
During reading time or a monitored break, confirm that student response areas remain locked.
On a reading paper, confirm that students can still open every text, read every question, and inspect every answer option. Reading time locks entry, not inspection.
At a section boundary, confirm that the previous section disappears and the next section's questions and tool rule appear.
During working time, monitor the online and submitted counts.

Watch candidate work as it is written

While a sitting is live, each session row offers Watch work:

Select Watch work on the live session.
Choose a candidate from the list on the left. Each row shows their candidate code, how many questions they have answered, and when they last saved.
Read their paper on the right: current answers, choice selections, drawing pages, and their notepad.
Leave the window open. It refreshes as candidates save, so you can see progress without walking the room.

What this shows and what it does not:

It shows what each candidate has saved. The candidate screen saves about a second after typing stops, so the very latest keystrokes can lag briefly.
A candidate whose browser is closed, offline, or crashed simply stops updating; the view keeps the last saved work and its timestamp.
It shows only PacePaper. It cannot see other tabs, other applications, or the candidate's screen.
It is read-only. Nothing you open changes a candidate's paper, and nothing appears on their screen while you watch.

Candidates are told at sign-in, and again in their waiting room, that their teacher can see their work during a sitting. 10. Let candidates with extra time continue until their individual time ends.

While an exam runs, the dashboard shows live Focus alerts when a candidate leaves the exam window, and the session keeps a per-session audit list; alerts are best-effort, so a crash or disconnect can prevent an event.

If a student's page says Reconnecting, keep the page open. Check that PacePaper is still running and that both devices remain on the same network.

Students normally finish by selecting Submit or Submit examination, checking their response summary, and selecting Submit now. Submission is final. PacePaper submits automatically when a student's time expires.

Select End exam only when the entire sitting must finish. A confirmation names the paper, class and students who have not submitted. Select Keep exam running to cancel, or End exam and submit remaining responses to finish. Confirming submits their last saved responses, including students who still have extra time. This cannot be undone.

If a student's work is not saving

Saved to server means the teacher's computer has the latest response.
Saved on this device means a browser recovery copy exists, but the server has not confirmed the latest response. Keep the page open and select Retry save.
Not saved means the latest changes are not confirmed safe. Keep the page open, tell the teacher and select Download recovery copy. Check that the download completed.
Restore the connection and select Retry save. Wait for Saved to server.

The recovery JSON file includes typed answers, canvas data and notes. It is an emergency copy for the teacher, not a submission or a paper import. If the teacher ends the exam before pending work is confirmed saved, the student page offers the recovery download again. Do not clear browser data, close the app, or rely on recovery after a browser crash.

Step 9 — Review and save candidate papers

Find the session on the teacher dashboard.
Select View submissions.
Open a candidate and check the saved response.
Select Print this candidate for one student, or Print all or save PDF for the group.
In the browser print window, choose a printer or Save as PDF.
Open the saved PDF and check it before closing PacePaper.

The printable record includes questions, typed responses, canvas pages, inline images, and the student's notepad. PDFs and audio used as companion materials are listed rather than reproduced inside the response paper.

Use a normal browser such as Chrome, Edge, or Safari. An in-app browser may ignore the print button.

PacePaper currently collects, reviews, and prints responses. It does not mark or grade them.

Rehearse the exam phases

To demonstrate the phase engine, use any sectioned paper you have built or imported:

Set up a session with a small demo class.
Open its clock on a second screen.
Join as a demo student in another browser.
Start the exam and watch each phase change.
Confirm that working sections accept only their own questions, the break hides examination content, calculator rules change where applicable, and only the final work section offers final submission.

Before assembling a demo class, Preview as student from Paper library shows the same interface, the phase order, and the paper's timings without creating a class, a student, or a stored response.

After the exam

Remove or restore items

Remove hides a class, student, or exam session without deleting earlier responses. Removed students cannot sign in, and removed classes cannot be used for new sessions.

Select Remove beside the item.
Read the confirmation message.
Confirm only after checking the name or session.
To bring it back, open the appropriate Removed section and select Restore.

A live session cannot be removed. A class with a live session must be ended first. A student with unfinished live work cannot be removed until that response is submitted or the session ends.

Back up all classroom data

Class-list and paper exports are not complete backups.

Finish every live exam.
Quit PacePaper completely.
Copy the entire PacePaper data folder to approved secure storage.

Default data folders:

Mac: ~/Library/Application Support/PacePaper/
Windows: %LOCALAPPDATA%\PacePaper\
Linux: ~/.local/share/PacePaper/

On a Mac, choose Go → Go to Folder in Finder and paste the path above. On Windows, press Windows-R and paste its path. On Linux, paste the path into the file manager's location bar. If IT set a custom data folder, use that folder instead.

These locations apply to the standalone app and bun run start:app. The basic development commands bun run start and bun run dev instead use the project's data/ folder unless configured otherwise.

Back up the data folder before replacing PacePaper with a newer version. Class-list CSV files move rosters; .digitaldp-paper files move individual papers. Only a complete data-folder backup also keeps the sessions and student responses.

Restore a backup

Stop PacePaper completely.
Make a separate copy of the current data folder so you can undo the restoration.
Replace the data folder's contents with the complete backup.
Start PacePaper and check a class, a paper, and a saved response.

Restoring a backup returns the installation to the date of that backup. Later work remains only in the separate copy you made in step 2. If you want to add a roster or paper while keeping current work, use its import option instead.

Student quick instructions

Teachers may give this section directly to students.

Open the address supplied by your teacher.
Enter the class code and select Load names.
Choose your own name and select Continue.
Choose the correct examination and select Join waiting room.
Wait for the teacher to start it.
Answer in the area below each question. Work saves automatically.
Use Flag and View summary to check unfinished questions.
Use the Notepad only for rough work. It is included in the teacher's PDF but is separate from your answers.
When finished, select Submit, check the summary, and select Submit now.

During reading time, answer areas remain locked. You can still read the questions and answer choices and switch between the available texts.

You may highlight text shown directly on the PacePaper page. Highlighting does not work inside attached PDFs or images. Accessibility controls can change text size, colours, typeface, or spacing without changing the paper.

For a drawing question, use Draw, Eraser, Undo, Redo, or Add page. You may choose Blank, Ruled, or Square grid under Canvas background.

For listening audio, select Start first listen only when ready and let it play to the end. After completion, Start final listen becomes available.

Troubleshooting

The Mac app says it is damaged: Do not bypass Gatekeeper. Confirm that the release is notarized. If you are working from a source checkout, use Start PacePaper.command from the project folder.
The app does not open: Extract the complete download, use the correct platform file, and close any second copy of PacePaper.
Students cannot connect: Confirm that classroom sharing is on, use the displayed private-network address, and test it on a real student device. Do not give students localhost or 127.0.0.1.
A student name is missing: Check the class code, select Refresh names, and confirm that the student is active in the correct class.
An exam is missing: Confirm that the teacher selected Set up exam. Ask the student to return to Choose your examination.
A student is stuck on Connecting or Reconnecting: Keep the page open. Confirm that PacePaper is running and both devices are still on the same network.
The clock is counting the wrong session: Choose the exam from the clock's session list, or reopen the clock from the correct session row.
Clock timing cannot be edited: Simple reading/writing papers support timing edits while the exam is ready or live — a live save moves candidate deadlines immediately. Fixed-section papers and ended exams use the saved schedule. Read Step 6; changing display details never changes student time.
The print button does nothing: Open the teacher dashboard in Chrome, Edge, or Safari, open View submissions, and select Print this candidate or Print all or save PDF again.

Demo safety

A fresh installation uses the default teacher login admin / admin; change it in Settings before real use. Students use a class code and choose a name; there is no PIN or identity check. Classroom traffic uses unencrypted HTTP.

Use fake candidates, approved practice material, and a trusted private network only. PacePaper is not the official IB Digital Examination System and is not affiliated with or endorsed by the International Baccalaureate.

FilesExpand file tree

USER_GUIDE.md

Latest commit

History