Administrator guide

Which administrator are you?

AIshie has just two platform roles, Root and Admin; together they are the platform administrators. Besides these, anyone can be appointed department administrator of a department. That is an appointment to one department, not a platform role.

• Root: the first account, made by the server’s operator at installation. Root signs in like everyone else, with an email (or a student/staff number) and a password. Only Root can make other platform administrators, and only Root can act on people who hold a platform role.
• Admin: given by Root when registering someone, and it cannot be given or taken away afterwards. An Admin can do everything else Root can.
• Department administrator: manages the courses and the department tree of the department they are appointed to and of every department beneath it (see Appointing department administrators).

To work in a course, for example to upload material or look at grades, you first seat yourself as instructor, and like everyone else you are then held to your seat’s permissions.

In the activity bar, select Administration. The side bar lists the administration pages you can open:

Anyone else who opens the address of an administration page is taken back to the home page.

Only platform administrators register people and handle terms, permission presets, single sign-on and service credentials. Creating, changing, activating, archiving and moving courses, seating instructors, purging content uploaded by mistake, changing the department tree and exporting conversations are shared between platform and department administrators, each within their own reach.

How the administration pages are laid out

• The activity bar and the side bar work as on every other page (see Finding your way around in the User guide): select Administration to open the administration side bar, and again to close it.
• The administration pages are laid out by the width of the page itself, not of the window: on a smaller laptop with the side bar open, when the page gets narrow, the list of people and agents changes from a table to one card per row; the lists of courses and departments stay tables but drop some columns and show them under the name instead; and two columns side by side stack one above the other. Dialogs float over the page and take none of its width. The AI and documents page works the same way.
• On a narrower page the department list drops its presets column and says it under each department’s name instead, such as “Presets: built-ins + 1 own”.
• On a phone, the activity bar and the side bar fold into Menu at the top left (see On a phone or in a narrow window in the User guide). Back first closes whatever covers the page, the Menu or the drawer of a permission preset or of a department’s administrators, rather than leaving the page; on a computer, the browser’s back closes those drawers too.

Setting up for the first time

A newly installed site has only one account, Root: no terms, departments or courses, and no single sign-on. Set it up in this order; each step links to the details.

1. Sign in as Root with the email and password the server’s operator gave you. Root has no seat in any course, so My courses is empty.
2. (Optional) In People & agents, register the other platform administrators, ticking “Platform administrator”, then create an invitation link for each. One account per person means every action later shows who did it.
3. In Terms, select New term (see Terms). A term cannot be renamed or removed once it is made.
4. In Departments, select New top-level department, then create departments beneath it (see The department tree).
5. (Optional) In Permission presets, create presets of a department’s own (see Permission presets).
6. In Courses, select New course, then seat the instructor.
7. Appoint department administrators at the top-level departments, so that they take over the day-to-day running of courses.
8. (Optional) In Sign-in, set up single sign-on.
9. (When the server has an agent service) In AI and documents, set up the school AI plan, and OCR and document transcription.

While there is no term or no department yet, the course page says “A course belongs to a term and a department, and there is none of one yet.” and offers Create a term and Create a department buttons. Department administrators are told instead that a platform administrator creates terms.

Terms

Administration › Terms (platform administrators only)

1. Select New term.
2. Fill in “Name” (such as “2026/27 Semester 1”), “First day” and “Last day”. The last day cannot come before the first.
3. Check the name and the dates, then select Create. A term cannot be renamed or removed once it is made.

The list shows each term’s dates and length, marked “Current”, “Upcoming” or “Ended”, and can be filtered by name. Everyone signed in can see the terms; only platform administrators create them.

Creating a course

Administration › Courses › New course

Platform administrators see the courses of every term and every department; department administrators see only those of the departments they administer and the departments beneath them. Filter the list by term and by department; with a department chosen, you can tick Include sub-departments.

1. Select New course.
2. Choose “Term” and “Department”, and fill in “Code” (such as CS101), “Section” (leave it empty when there is only one section), “Title” and “Description”. Within a term, code and section together must be unique.
3. Select Create course. The new course is a draft with no members, and its administration page opens. Next, seat the instructor.

Seating the instructor

Administration › Courses › a course › the “Seat the instructor” card

A new course has no members until its first instructor is seated. The instructor gets the built-in “Instructor” permission preset, and then adds everyone else from the course’s Members page (see Adding a member in the User guide).

Platform administrators

1. In “Instructor”, search by name or email, or paste their ID; to seat yourself, select Me.
2. Select Seat as instructor.

If you cannot find them, they are not registered yet: register them in People & agents first, then come back and seat them.

Department administrators

1. Type the person’s whole email or whole student/staff number and select Find (there is no partial search); to seat yourself, select Me.
2. Select Seat as instructor.
3. If nobody is found by that email, select Invite someone new, fill in “Name”, “Email” and how long the link works for, and select Register and invite. Copy the link shown and hand it to them yourself (AIshie sends no email), then select Seat [name] as instructor. If nobody is found by a student/staff number, no invitation is offered: find them by email instead.

When the person has not signed in yet, the result of the search offers Invite again: the new link replaces the one they were given. As a department administrator, you can invite again only someone who has never signed in, holds no platform role, administers no department, owns no agent, and has seats only in courses you administer. Otherwise there is no Invite again button (and the page gives no reason): ask a platform administrator to create an invitation link.

Once the course has members, this card lists its instructors (or whomever you seated from this page), and offers Go to the Members page and Seat another instructor. The Members page opens only to the course’s members: if you have no seat there, seat yourself first.

Course status: draft, active, archived

Administration › Courses › a course

• Reopen: members can work in the course again. Seats that expired, proposals that went stale and due dates that passed while it was archived are dealt with when it reopens.
• Edit: changes only the course’s title and description. A course’s code, section and term are what it is, and cannot be changed. Instructors can also change the title and description on the course’s overview page.
• Move to another department: members, seats and everything in the course stay as they are; who administers it changes with its department, and the administrators of the old department who do not administer the new one lose it at once. A department administrator can move a course only to a department they also administer.
• Open course: shown only when you have a seat in the course.

Once a course is archived, editing and moving are not available: reopen it first.

Purging content uploaded by mistake

When material, an assignment’s instructions or a rubric carries something that should not be shared (such as a student’s personal data), it can be purged for good. Only a platform administrator, or an administrator of the course’s department (or of a department above it), can purge: removing data is not something any course seat can do. The buttons are on the document’s page, so you need a seat in the course to open that page. An archived course can be purged too.

1. Open the document and select Purge… (which purges every version of the whole document), or select Purge this version on one version.
2. Fill in “Why” (required, at most 500 characters). The reason is kept on the tombstone and shown to whoever reads the document.
3. Tick “I understand that this removes it for good” and select Purge.

• The text and the files are removed, and the files are deleted from storage; this cannot be undone. A version can have several files: purging it deletes all of them, together with their text versions and PDF previews. When it is done, the page says how many versions were purged and how many files were deleted.
• A purged version stays in the version history as a “Purged” tombstone, saying who purged it, when and why. If the purged version is the published one, it stays the published version until another is published.
• Once the whole document is purged, it is archived for good: nothing can be added to it, and it cannot be brought back.
• Work handed in under a purged version still names it and shows the tombstone; grades are untouched.
• The course’s Activity shows “One version purged” or “The whole document purged (n versions)”.
• The text the school’s agent service keeps so that agents can search the material is no longer found once it is purged, and is deleted from the agent service within 30 days at most.
• Where an AI agent’s answer relied on the purged version, the line under the answer shows it to every reader, staff included, only as “a course material you cannot open” (see The course materials an answer relied on in the User guide).

The department tree

Administration › Departments

Platform administrators see the whole department tree; department administrators see the departments they administer and everything beneath them. Each department shows how many courses it has (select it to open the list of courses directly in that department) and how many administrators (select it to open the administrators drawer). Platform administrators also see each department’s permission presets, such as “View (built-ins + 1 own)”.

• New top-level department: platform administrators only.
• New department here: departments nest at most 8 levels deep, and two departments at the same level cannot share a name. A department cannot be removed once it is made, but it can be renamed or moved.
• Rename, Move, Administrators (appointing): a department administrator can do these only to departments beneath the one they are appointed to, never to their own department or those above it.

Moving a department

• The departments and courses beneath it move with it. Administrators who administered them only through the old department above lose that at once; the administrators of the new department above gain it at once. Everything inside the courses stays as it is.
• Destinations you cannot choose say why: “where it is now”, “too deep for what moves with it” or “a department there has its name”. A department cannot go under itself or under a department beneath it.
• A department administrator can move a department only under one they also administer; moving one to the top of the tree is for platform administrators only.

Appointing department administrators

1. In the department’s row menu, select Administrators to open the administrators drawer.
2. Under the drawer’s “Appoint an administrator” heading, type the person’s whole email or student/staff number, and select Find.
3. Select Appoint [name].

The drawer lists the administrators appointed here, and those who administer it through a department above (marked “Through [department above]”); each appointment says who made it and when. Turn on Show past appointments to see appointments that have ended, and who ended them.

A department administrator can create, change, activate, archive and move the courses of these departments, seat instructors, create departments beneath them, and rename, move and appoint administrators for the departments beneath them. An appointment does not give a seat in any course.

Permission presets

Administration › Permission presets (platform administrators only)

A permission preset is a starting point for a new member: a roster role, the students and assignments it reaches, and a level for each of the seventeen permissions. When a member is added to a course, the preset is copied onto their seat. For the permission levels, the seventeen permissions, the built-in presets and the rules nothing can override, see The four permission levels, The seventeen permissions, The built-in presets and Rules nobody can get around in the User guide.

Where a permission’s level is “Needs approval”, AIshie first checks the request as it would on approval: if approving it now would be refused (for example publishing a version that is already published, revoking a link that is already revoked, seating someone who already has a seat, or an expiry time that has passed), it is refused at once with the reason, and does not become a proposal.

The page has two views: Presets (a card for each preset) and Compare permissions (a matrix with a column for each preset). By default only the built-in presets are shown; choose a department to see its own presets beside the built-ins.

The 8 built-in presets (Student, Observer, Teaching assistant, Instructor, Tutor (agent), Grader (agent), Personal agent, Course agent) ship with the installation and cannot be edited. To give a department something different, open a built-in preset and select Copy into a department preset.

Creating a department preset

1. Select New preset.
2. Choose “Department” (required: every preset belongs to one department), and fill in “Name” (unique within the department, though it may share a built-in preset’s name) and “Description”.
3. (Optional) In “Start from”, choose an existing preset to fill in its role, reach and permissions.
4. Choose the “Roster role”, and the “Students reached” and “Assignments reached”: All, or Listed only (the list is chosen when a member is seated). A student whose list of students is left empty is listed themselves; any other list left empty reaches nothing.
5. Set each permission’s level; anything left at “Denied” is not permitted. Select Create.

• A preset’s name and department cannot be changed once it is made, and a preset cannot be deleted.
• Edit replaces the preset’s description, role, reach and every permission. Members already seated from it keep what they were given; only members added afterwards get the new values. A member’s seat can be adjusted on its own inside the course (see Changing a member’s permissions, reach and role in the User guide).

The people and agents directory

Administration › People & agents

Search by name, email or student/staff number, or paste an ID; filter by kind (People, Agents) and by status. The “Sign-in” column shows how each person can sign in:

• Password, Single sign-on: they can sign in.
• Invited until [date]: an invitation link has been created, and they have not used it yet.
• Invitation expired: the link expired unused; create a new one.
• No password or single sign-on yet: they cannot sign in yet.

Registering a person or an agent

1. Select Register, and choose “Person” or “Agent” as the “Kind”.
2. Fill in “Display name”. A person can be given an “Email” and a “Student/staff number”: both are optional, but signing in with a password needs at least one of them. Each belongs to one person only, and can be changed later but not removed. A student/staff number may use only letters, digits, dots, hyphens and underscores, up to 64 characters, with no @.
3. For an agent, choose “How it runs”: Hosted on AIshie (run by the school’s agent service) or MCP access (connecting from an AI tool elsewhere with API tokens). Choose an “Owner” if it needs one (see below).
4. Only Root can tick “Platform administrator”: ticking it makes them an Admin (an agent with an owner cannot be ticked).
5. Select Register.

After registering

• A person: create an invitation link on their page, or link their single sign-on identity. Then seat them in a course: seat them as instructor on the course’s administration page, or ask the course’s instructor to add them on the Members page.
• An agent with an owner: its owner hosts it on AIshie or issues it tokens from My agents, and brings it into their own courses. It is never seated from the course’s Members page.
• An agent with no owner and MCP access: issue it an API token on its page, then ask a course’s instructor to seat it with a preset such as “Grader (agent)” or “Tutor (agent)”, scoped to the students or assignments it serves.
• An agent with no owner, hosted on AIshie: no token is issued for it here. The agent service runs it, and is issued its token itself, once the agent service’s operator names it by this agent’s ID (see the Operator guide).

Invitation links (choosing a password) and password resets

People & agents › a person › the “Invitation link” card

An invitation link lets the person choose a password and signs them in straight away. AIshie sends no email: you hand the link to them yourself.

1. Choose how long “The link works for”: 1, 3, 7 (the default), 14 or 30 days.
2. Select Create invitation link. When an unused link exists already, the button is Create a new link; when they have a password already, it is Create a link to reset their password.
3. The link is shown only once: copy it at once and give it to them in a way you trust. Whoever opens the link chooses the password.

• A person has at most one working link at a time: creating a new one replaces the old. A link works once.
• Resetting a password: when someone forgets their password, create a link to reset it. Once they use it, the new password replaces the old one.
• Changing their email withdraws the link waiting for them: create a new one after the change.
• No link can be made for: yourself (set your password on your Account page), the system account, an agent (issue it a token instead), a suspended person (reactivate them first), someone with neither an email nor a student/staff number (give them one first), or someone who holds a platform role (only Root can).

For what the person sees when they open the link, see Setting a password from an administrator’s link in the User guide.

Editing, verifying a student number, suspending

People & agents › a person

• Edit: change the display name, the email and the student/staff number. The kind and the platform role do not change. Only platform administrators can change a student/staff number; people cannot change their own.
• Verifying a student number: when someone made their own account through a course’s invite link, the student/staff number they typed is marked “Unverified”. Once you have checked it, tick “I have checked it: save it as confirmed” under Edit and save; correcting it to the right number counts as confirmed too.
• Suspend: everything they do in every course is refused, and they cannot sign in; the same goes for agents. Their seats, history and credentials are kept, and Reactivate brings them back as they were. You cannot suspend yourself; only Root can suspend someone who holds a platform role; the system account cannot be suspended.
• An agent suspended by its owner: the top of the page says so. Reactivate here lifts the suspension too; Take over the suspension makes it yours, and then the owner cannot lift it themselves.
• An agent’s page shows its “Owner” and “How it runs” (both set when it was registered, and never changed); a person’s page lists the “Agents they own”.

Tokens and sign-ins

People & agents › a person › the “Tokens and sign-ins” card

This card lists every way into the account: browser sessions, a password, single sign-on identities and an invitation link. You can Revoke them one at a time without suspending the person; their other credentials and their seats are kept. Turn on the Show revoked and expired switch to see past ones.

• A password an instructor reset is marked “Temporary”, with who set it: the person must choose their own at their next sign-in.
• A single sign-on identity shows its “Account” and who it was “Linked by”; an invitation link shows who it was “Invited by”.
• People have no API tokens: if a person is listed here with a token, revoke it.
• Revoke your own credentials on your Account page, which can tell which session is the one you are using.

An agent hosted on AIshie has a single token, which the school’s agent service is issued; its issuer shows as “The site’s agent service”. Once it is revoked, nobody on the site can ask this agent anything until the agent service is issued a new token, and the owner sees on the agent’s page that it needs reconnecting.

Issuing an API token to an agent

People & agents › an agent with MCP access › the “API token” card

An agent cannot sign in to ask for a token, so its first credential comes from here. An agent with an owner usually gets its tokens from its owner, in My agents (see Tokens in the User guide).

1. Fill in “Label” with what it is for, such as “grader for CS101, autumn term”.
2. Choose when it “Expires”: 30 days, 90 days (the default), 365 days, Never, or “Other…” with 1 to 3650 days.
3. Select Issue token. The token is shown only once (Core keeps only its hash): copy it at once.

The result also gives the MCP connection details: the endpoint (streamable HTTP) and the header. Point the agent’s MCP client at that endpoint, with the token as a bearer token. If a token leaks, revoke that one in “Tokens and sign-ins”; the agent itself is not suspended. No token is issued here for an agent hosted on AIshie.

Accounts made through a course’s invite link

Instructors can make an invite link or QR code for their course that works for 10 minutes (see Invite links and QR codes in the User guide). Someone without an account can make their own through it, and join the course as a student.

• For an account made this way, the student/staff number and the email are whatever the person typed, and nobody has checked them: the number is marked “Unverified”; confirm it as in Verifying a student number.
• An email someone typed themselves is never used to link single sign-on by email.
• The server’s operator can turn off making accounts through these links (for instance once the school uses single sign-on for everyone): the link then offers only “Sign in to join”, and the person must have an account first. This is a server setting; see the Operator guide.

Single sign-on: before you start

Administration › Sign-in (Root and platform administrators only)

• AIshie works with OpenID Connect identity providers. The dialog explains, for AD FS, Microsoft Entra ID, Google Workspace and Keycloak, where to register and what to give as the issuer URL.
• Single sign-on creates no accounts: an identity provider vouching for someone does not mean they have an account on AIshie. Register these people first, then link their accounts at the provider.
• Client secrets are kept sealed on the server with SECRETS_KEY. When the page says the server’s operator has to give the server a key to seal client secrets with (the ⓘ beside it names it: SECRETS_KEY), no provider can be added until the operator does; for setting, keeping and replacing this key, see the Operator guide. A new server set up with AIShie-Deploy has it already.
• The server reaches only providers at public network addresses. When the provider is on the school’s internal network (for example an AD FS whose name resolves to an address beginning 10.), or the server reaches the internet through a proxy, ask the operator to set SSO_ALLOW_PRIVATE_ISSUERS.

The whole process is: add a provider (a new provider is switched off) → link accounts → test it and switch it on.

Adding a provider

1. Copy the Redirect URI at the top of the page (https://your-address/v1/auth/sso/callback), register an application at the identity provider, and give it this as the redirect (reply, callback) URI. Every provider uses the same one.
2. Select Add provider. The top of the dialog shows the redirect URI again, with how to set up each kind of provider.
3. Fill in “ID” (lower-case letters, digits and hyphens, up to 64 characters, such as school-adfs; accounts are linked by it, and it never changes) and “Display name” (the name on the sign-in button, up to 64 characters).
4. Fill in “Issuer URL”: exactly as the provider’s discovery document (…/.well-known/openid-configuration) writes it, a trailing / included, and it must be https.
5. Select Test beside the issuer. The test reads only the provider’s discovery document and keys: it signs nobody in and sends no secret. The result is “Ready” or “Not ready”, with any problems, the endpoints and the signing keys.
6. Fill in “Client ID” and “Client secret”. The secret is sealed before it is kept, and from then on only its last four characters are shown.
7. Open “Advanced” if needed (see below), then select Add provider. A new provider is switched off: its button is not on the sign-in page yet.

When the test report says “An address here is on this machine, or private, link-local or reserved”, the server will not reach this provider: ask the server’s operator to set SSO_ALLOW_PRIVATE_ISSUERS, then test again.

Advanced

• Scopes: what a sign-in asks for; openid is always among them, and there can be up to 20.
• Subject claim: the claim an account is known by, which is the value used when linking. It is sub unless the provider says otherwise; AD FS uses upn.
• Email claim: read only when linking by email.
• Place on the sign-in page: 0 to 10000, lowest first. A provider the server’s operator set is always first.
• Link existing accounts by verified email and Allowed email domains: see Linking accounts.

Linking accounts

Each person’s account must be linked at a provider before they can sign in through it. There are two ways:

One at a time

1. In People & agents, open the person and find the “Single sign-on” card.
2. Choose the “Provider”, and fill in their “Account” at the provider, which is the value of the subject claim (for AD FS, the UPN, such as name@example.edu; letter case does not matter where it has an @). You can select Use their email.
3. Select Link identity.

An identity links to one person only, for good: once linked, it is never passed to anyone else. Agents do not use single sign-on.

Linking by email

Under the provider’s “Advanced”, turn on “Link existing accounts by verified email” and list the allowed email domains (up to 50). From then on, someone signing in through it for the first time, whose identity is not linked to any account yet, is linked to an existing account when all of these hold:

• the provider vouches for the email: the email claim of the ID token carries it, and email_verified is true;
• the email is in one of the allowed domains, exactly (a subdomain is another domain);
• the account with that email belongs to an active person, whose email was given by an administrator rather than typed in by the person through a course’s invite link;
• the account holds no platform role (Root and Admins are linked one at a time);
• the account is not linked at this provider already.

Anyone else is refused as not registered, and no account is created. An identity that was once unlinked is never linked by email again. AD FS and Entra ID send no email_verified: with them, this setting links nobody, so link accounts one at a time.

Testing, switching on, switching off

1. With the accounts linked, select Test in the list and check once more that it is “Ready”.
2. Switch it on in the On column. Within a minute its button is on the sign-in page. If no account is linked at it yet when you switch it on, the page reminds you that nobody can sign in through it until one is.

This is the button people see on the sign-in page (for what they do, see Signing in in the User guide):

• Switch off: within a minute the button leaves the sign-in page. Every link is kept, and switching it on again makes it work again.
• Edit: change the display name, the issuer, the client ID, the secret (choose “Replace it with a new one”) and the advanced settings; changes take effect at the next sign-in. When you change the issuer, accounts linked at it stay linked: whoever the new issuer vouches for under the same subject signs in as them. If another administrator changed the same provider meanwhile, the page says “Someone changed this provider meanwhile”: check it and save again.
• Delete: when accounts are still linked at it, the dialog says how many will lose single sign-on, and the button reads Delete and unlink n accounts. Those people can then sign in only with a password, or not at all. Creating a provider with the same ID later does not link anyone back. To pause it, switch it off instead.

Statuses in the list

• The Older key tag: the secret was sealed with an earlier SECRETS_KEY, which the server still holds. The tag goes away once the operator finishes replacing the key.
• Set by the server’s operator: a provider the operator set in the server’s environment (OIDC_*) is always on, and can be seen here but not changed; the ⓘ beside it says which settings.

AI and documents: who can use it

Administration › AI and documents

• This item appears in a platform administrator’s side bar only when the server has an agent service.
• By default, the agent service’s administrators are all of AIshie’s Root and Admins. The server’s operator can name only some of them with the agent service’s ADMIN_ACTOR_IDS; a platform administrator not on that list who opens this page sees “You are not one of this agent service’s administrators”.
• “This server has no agent service” or “The agent service cannot be reached”: the first is for the operator to set one up; for the second, the agent service may be restarting, so select Retry after a minute.

The page has five tabs: School AI plan, Pricing, Usage today, Documents and Agent hosting. Where the agent service does not offer a feature yet, the tab says so.

• Changes here take effect within moments, with no restart; each setting says “Changed by [name], [time]”. If another administrator changed the same setting meanwhile, the page shows it as it is now: check it and try again.
• The time of day when the counts start again is shown in your time zone, with the zone named; hover over the time to see it exactly in UTC. The agent service counts days in UTC by default, so in a UTC+8 region it shows as 08:00. Transcription’s “Today” counts by the UTC day too, and says below it when the counts start again each day. A price’s “From” is a day in UTC, and the field says below it when that day begins in your time zone, for example “The price starts at 2026-10-03 08:00 (Hong Kong Standard Time), when the day chosen begins in UTC.”

The school AI plan

The models the school provides and pays for, on the school’s own API keys. Agent owners can choose one of them for their agents hosted on AIshie, with no key of their own (see Hosted on AIshie in the User guide). The keys stay on the server, and nobody can see them.

Adding a model

1. Under “Models on the plan”, select Add a model.
2. Fill in “ID” (letters, digits, _ and -, up to 64 characters; agents name the model by it, and it cannot be changed later) and “Name shown to owners” (one line, up to 80 characters, such as “School AI (fast)”).
3. Under “Model”, choose the provider and the model; some providers also need an endpoint, resource or region.
4. Fill in “The school’s API key”. Before it is saved, the agent service tries it with one short call; if the trial fails, nothing is saved. When it cannot be tried just now, tick “Keep the key without trying it”, and it shows as “Not tested”.
5. Turn on “Offer it to owners” if you want to, and select Add.

• The key goes to the agent service, which keeps it sealed; from then on only its end is shown.
• Turning off or deleting a model: owners no longer see it. An agent on it switches to its owner’s own model where the owner has set one as a fallback; the others pause until their owner chooses another model. Deleting also deletes, for good, the key the school set for it; if it is added again later with the same ID, those agents use it again.
• Models the server’s operator set in runtime.yaml are marked “Read-only”. Models the operator’s model lists do not allow are marked “Not allowed”, and are not offered.

Daily quotas

How many answers the school’s plan may give a day, and (once every model has a price) how many dollars a day. Leave one empty for no limit.

• Per owner: across all of one owner’s agents.
• Per person asking: for each person who asks one agent, in one course.
• For the whole school: everything on the school’s key, whoever’s agent answers, including the operator’s agents on the school’s key and (in dollars) document transcription. Use on anyone’s own key is not counted.

A quota in dollars needs a price for every model of the plan (see Pricing). Use the server’s defaults goes back to the settings in runtime.yaml. Every agent keeps new quotas from its next answer.

Owners also see the school plan’s daily quotas, and the time the counts start again, on their own agent’s page, in their own time zone, so administrators and owners are talking about the same moment.

Upstream routing for an OpenRouter model

Administration › AI and documents › School AI plan › Add a model (with OpenRouter as the provider)

OpenRouter does not run models itself: it passes each call to one of the upstream providers that serve the model. When you add or edit an OpenRouter model on the school’s plan, the dialog has a section more, “OpenRouter upstream routing”: you can choose which upstream providers may answer, which to try first, and the terms they must meet. These settings are sent to OpenRouter with every call. Left as they are, OpenRouter chooses by price and uptime.

1. Under “Models on the plan”, select Add a model, fill in the ID and the name, and choose OpenRouter as the “Provider”.
2. Under “Model”, give OpenRouter’s ID of the model, such as meta-llama/llama-3.3-70b-instruct. A moment later, the upstream providers OpenRouter lists for it appear below; if the ID is wrong, it says “OpenRouter has no model …. Check the model’s ID.”
3. Fill in “The school’s API key”. The agent service tries it with one short call as usual (the trial does not send the upstream routing).
4. Set the “OpenRouter upstream routing” as you need (see below), look at what will be sent under What is sent to OpenRouter at the foot, and select Add.

A model newly added has three settings on already: only upstream providers that keep no data; letting OpenRouter use other upstream providers when those tried first cannot answer; and only upstream providers that take every setting of a call.

Data and upstream providers

• Only upstream providers that keep no data: leaves out upstream providers that may store what is sent to them and train models on it. Recommended for a school.
• Only zero-data-retention (ZDR) endpoints: stricter still, only endpoints that keep nothing of a call once it is answered. Fewer upstream providers qualify; the list marks those that do “ZDR”.
• Under “Which may answer”, choose All, except those turned off (those turned off in the list are not used) or Only those turned on (only those turned on are used). The fewer there are, the less is left to fall back on when one is down.
• Each row of the list is an upstream provider’s endpoint: its name and slug, the precision it runs the model at, its context, its most output, where it is based, its price for input and output per million tokens (hover over the price for a discount, or a higher price for long inputs), whether it calls tools, its uptime over the last 30 minutes and day, and its “Privacy”, “Terms” and “Status” links. One not running normally is marked “Not running normally”.
• The “Use” switch decides whether it may answer; one left out by a setting above says “Left out by: …”. A slug without “/” (such as google-vertex) names every endpoint of its provider, its regions included, and the endpoints under it say “Included in …”.
• Try first: these upstream providers are tried first, in an order you change with Try earlier and Try later, or Do not try first.
• Add by slug: an upstream provider the list does not show can be added by its slug, such as deepinfra/turbo.
• Under the list it says “As OpenRouter listed them at ….”; when OpenRouter cannot be reached just now, a list read within the last hour is used, and the page says so.

Choosing among them, speed and limits

• If those tried first cannot answer, let OpenRouter use others: off, a call goes only to those tried first (with none chosen, to the one OpenRouter picks first), and fails when they cannot answer.
• Only upstream providers that take every setting of a call: an upstream provider that cannot call tools, or would ignore a setting such as the reasoning effort, is never used. Recommended.
• “Choose among them by”: OpenRouter’s balance of price and uptime, Lowest price, Fastest output, Quickest to start answering, or Best at calling tools (Exacto). It is not used while some upstream providers are tried first.
• “Preferred speed”: output speed and the time to the first token, at the median (p50), p75, p90 or p99 over the last 5 minutes. Upstream providers that miss these are tried last, not left out.
• “Limits”: “Precision the model runs at” uses only upstream providers that run the model at one of the precisions chosen, any if none is; “Highest price accepted” (input and output per million tokens, per call, per image) leaves out upstream providers that charge more, and with none left, the call fails.

Prices

OpenRouter charges what the upstream provider that answered charges, but the school’s quotas in dollars and its costs report use one price for each model: every call is counted at the price table’s price for the model, whichever upstream provider answered (see Pricing). The dialog gives the highest that the upstream providers allowed charge, and the price table’s price. When the price table’s is lower, it warns that the school could spend more than its quotas say: select Set the price to raise it to at least the highest, or set a highest price accepted.

What is sent, and the plan’s list

• What is sent to OpenRouter: opened, the settings sent with every call (OpenRouter calls them provider). With nothing set, it says “Nothing: OpenRouter routes each call as it does by default.”
• Clear the upstream routing: every setting above goes back to OpenRouter’s own, and nothing is sent with the calls.
• Under “Models on the plan”, a model with upstream routing has Upstream routing after its ID; select it to see what is “Sent to OpenRouter with each call”. A model the server’s operator set in runtime.yaml shows the same, to view only.
• Changing only the upstream routing does not try the key again. Change the model to another provider, and its upstream routing is removed.
• When the server’s agent service is older and does not take upstream routing yet, the dialog says “This server cannot list OpenRouter’s upstream providers yet.”, and saving says “This server does not take upstream routing yet. Save without it, or ask the server’s operator to update.”, offering Save without upstream routing: only when you select it is the model saved without its routing. Ask the server’s operator to update the agent service (see Versions these guides describe in the Operator guide).

Pricing

• Prices: what models cost, in dollars per million tokens (input, cache read, cache write, output), by provider and model (* stands for any text, as in gpt-4.1*) and a “From” day (a day in UTC, which may be in the future). Prices are shown in US dollars, written US$, as in US$0.40. Prices from the server’s price file can only be viewed; a price added here for the same model and day stands before it. A change applies to calls from then on; costs already recorded keep the price they had.
• Quotas per person: how many answers, and how many dollars, all of one person’s agents may use of the school’s key a day, in place of the setting in runtime.yaml until it is reset. They cannot both be left empty.
• Agents’ daily budgets: the most each agent hosted here may use a day, on whichever key it answers: for each agent in all, and for each person asking it in a course. The server’s own configured agents keep the budgets runtime.yaml gives them.
• What things cost: the recorded costs (in dollars) by day, person, agent, model or key, or in total; for keys, choose all keys, the school’s key or owners’ own keys, over at most a year at a time. Document transcription is a line of its own. A call that had no price when it was made counts as US$0.00, and is marked so.

Usage today

Today’s answers, model calls and cost on the school’s plan, against the whole school’s daily ceiling, and by owner. The page says “Since [time]. The counts start again at [time].”, in your time zone. The cost here leaves out document transcription, though the whole school’s ceiling in dollars counts it too.

Documents: OCR and transcription

Reading scanned documents (OCR)

When a model cannot read a file itself, the agent service recognizes the text of scanned PDFs and images for it, in the languages chosen here.

• Turn it on or off, and choose up to 8 languages, which are read in the order you chose them; or select Use the server’s default.
• When the server’s operator has turned OCR off, or OCR is not installed on the server, the status is “Not available”: what you set is kept for when it can run.

Transcribing documents (text versions)

The agent service uses a model of the school’s plan, on the school’s key, to transcribe each version of the courses’ files (slides, PDFs, Word) into a text version once: every model reads this text version, and readers and staff see it beside the file too. It is off by default.

1. First, add a model that reads PDFs or images to the school AI plan. Give it a price in the price table; otherwise the whole school’s ceiling in dollars cannot cover what transcription costs.
2. Under “Credential with AIshie”, select Issue and give to the agent service: AIshie issues a credential for the transcription service and hands it straight to the agent service, which tries it first. The credential is never shown on screen, nor kept in the browser.
3. Choose the “Model”, and adjust “Pages a document at most” (1 to 5000, default 300), “Pages a day” (empty for no limit) and “Documents at once” (1 to 8, default 2) if needed.
4. Turn on “Transcribe documents into text versions”.

• Status: Off, Running, Standing by, or Blocked with the reason (no credential, AIshie refused its credential, no model chosen, its model is not available, today’s pages are used up).
• When a version has several files, each is transcribed on its own, and “What it transcribed” marks them “File n”. A document with more pages than the limit is skipped; once the day’s pages are used up, documents claimed are skipped too, and staff can send them again later.
• The school pays the cost, which counts towards the whole school’s ceiling in dollars and towards no owner’s quota; in the costs it is listed as “Document transcription”.
• When agents search the course material, scanned files and files that can be read only through their text version are found only once they are transcribed.
• The credential can be replaced (Replace) or revoked (Revoke); once it is revoked, no file is transcribed until a new credential is issued. When the number of credentials reaches the limit, select Replace them all. Only AIshie’s platform administrators can issue or revoke this credential.
• When transcription is turned off, text versions already written stay, and staff can still write them themselves (see A file’s text version in the User guide).

Agent hosting: the agent service’s credential for AIshie

The agent service calls AIshie with a credential of its own (aissvc_…): with it, the agent service checks who owns an agent, is issued and revokes the token of each agent it hosts, and also claims Office files and hands back the PDFs it made of them. Without a live credential it hosts no agent and turns no Office file into PDF.

• The card lists each credential’s state (Live, Revoked, Expired), who issued it (one made when the server was set up shows as “The server, at setup”), when it was issued and when it was last used.
• Replacing it: ask the server’s operator to run aishie runtime-credential on the server, which issues a new credential, revokes the others, and has the agent service use the new one (see the Operator guide).
• After you Revoke the credential in use, the agent service hosts no agent and turns no Office file into PDF until it is given a new one. The agents’ own tokens are not revoked.
• Issue a credential: a credential issued here is shown only once, and nobody hands it to the agent service: the operator must put it on the server. Normally, use the command above.

Exporting conversations for audit

Administration › Export conversations

The full record of conversations can be exported as JSON Lines and CSV files. Exports are made by people; agents cannot export.

1. Choose “Conversations of”: a course, a department or the whole site. For a course, search by its code or title, or paste its ID; a department includes the courses of every department beneath it.
2. If you need to, choose a “Participant”, to export only the conversations this person asked in, or this agent answered. Platform administrators can search by name, email or student number; department administrators type a person’s whole email or student/staff number, or paste an agent’s ID.
3. If you need to, fill in “From” and “Up to and including”. The days are on your calendar and in your time zone, and the page shows the exact times sent.
4. Select Export. A large export can take a few minutes; you can go to other pages meanwhile, and the result shows here when it is done.

An export holds every message of the chosen conversations (withdrawn messages with their text, marked as withdrawn), a description of the files each message carries (ID, name, type, size and checksum, not the files themselves), and the answers and questions that were proposed but never posted (including those rejected or sent back for changes). The files hold no tokens, passwords or secrets. The result shows the number of conversations, messages and proposals, and gives two files with their checksums:

Every time in the files is recorded in UTC.

• Limits: by default an export holds at most 100,000 messages (proposals included) or 256 MiB of text. Past that, the page says “Not exported”, and suggests exporting one course, only one participant, or fewer days.
• If the connection drops: export again with the same choices, and the server gives back the export it made rather than exporting twice.
• Nothing can be exported when the server has no file storage set up: tell the server’s operator.

Exports you made in this browser whose files are still on the server are listed under “Recent exports”, to download again. This list is kept only in this browser.

Action records and activity

• Every administrative action is recorded: who did it, when, and in what capacity (as a platform administrator, or under which department’s appointment).
• Actions on a course, such as creating, changing, activating, archiving and moving it, and purging content, appear in that course’s Activity, where course members see them as their own seat’s permissions allow (see Activity and My actions in the User guide).
• Actions on departments, appointments, accounts, single sign-on and exports belong to no course, and do not appear in any course’s activity. The site has no page listing these records yet; when you need to look at them, ask the server’s operator.