Members' computers

Administrator·5 minutes to read

Organisation → Computers is visible only to an owner or an administrator of a team organisation. It lists every member's computer and lets you act on many of them at once.

What this does for you

This page shows an administrator how to recreate, terminate or wipe many members' computers at once — from Organisation → Computers or through the organisation API — and how to end computers unused for 30 days automatically.

The three operations differ in what survives:

Recreate replaces the machine on the current image and setup scripts. The member's files and sign-ins stay on the disk.
Terminate ends the machine and keeps its disk. The member's next message starts a fresh computer with the same files and sign-ins.
Delete computer and data ends the machine and deletes its disk and everything on it. This cannot be undone.

Before you start

You are signed in as an owner or an administrator, on Organisation → Computers.
On the hosted service, recreating and terminating are part of the Enterprise plan; deleting a computer and its data is available on every plan.
Only one operation runs per organisation at a time. If one is still running, wait for it to finish before you start another.
To use the API, you have an organisation API key with the admin scope. A read-only key is refused.

Steps

Open Organisation → Computers. Under Many members at once, type a name or an email address into Search members to narrow the list.
Select members one at a time, or press Select all in the results to select every member the current search shows (and only those).
Press Recreate, Terminate or Delete computer and data. A confirmation restates the operation and the number of members it will act on. Press Run to start it, or Cancel.
Watch the progress card. It shows how many members are queued, running, complete, skipped and failed, and one row per member with their result and, when a member was skipped or failed, the reason: no computer, left the organisation, another recreate running, or failed. The operation runs on the server: you can close the page, and reopening Organisation → Computers shows the same operation's progress.
To end computers nobody uses, turn on End computers unused for 30 days. It is off until an administrator turns it on. With it on, a computer that has been stopped and unused for 30 days is terminated with its disk kept; a computer that is awake is never ended. The member's next message starts a fresh computer with their files and sign-ins.

Through the organisation API

The same three operations are in the organisation API, behind an admin key:

POST /api/v1/organisation/computer-operations starts one operation. The body names the action (recreate, terminate or delete) and the memberUserIds to act on, and the request carries an Idempotency-Key header. A retried start with the same key finds the operation it already made rather than running the work twice. The answer is the operation, with its counts and one result per member.
GET /api/v1/organisation/computer-operations/{id} reads an operation's counts and per-member results, each with its reason.
GET /api/v1/organisation/computer-operations/latest reads the newest operation, so a caller that lost the id still finds the one it started.

A start while another operation is running is refused with 409 conflict and a reason, and changes nothing — whether the running one was started from the screen or the API.

A worked example

Your team moves to a new set of setup scripts. You open Organisation → Computers, search for @design.example, press Select all in the results (twelve members), press Recreate, read "Recreate for 12 members. Their files and sign-ins stay on the disk." and press Run. The progress card ends with ten complete and two skipped: one member has no computer yet, and one left the organisation while the operation was queued.

What can go wrong

"Another operation is already running for this organisation." Only one runs at a time. Wait for the progress card to read Finished, then start the next.
A member is skipped. The row names why: the member has no computer, has left the organisation, or already has a recreate running. Nothing was done to that member's computer.
A member failed. The row says failed; the rest of the operation carries on. Run the operation again for that member.
The API answers 403. The key is read-only, or the operation needs the Enterprise plan.

Every operation, and every computer ended by the 30-day rule, writes an audit row naming the member and the outcome.