Server Management

Overview

This page is a reference for server-side operation of RemoteRF. It covers the primary commands used upon starting the RemoteRF server via serverrf -s.

As usual, be sure to activate the remoterf-server environment using conda before starting the server. This can be done by opening a new terminal and then typing in:

conda activate remoterf-server
serverrf -s

Version Note: This page tracks the command surface used by the current RemoteRF deployment docs. If your installed package prints different help text, treat serverrf --help and help inside the running server shell as the source of truth for that installation.

Static Shell

Static shell commands are typed into the normal operating-system terminal, before you enter the running server@remoterf: prompt. Use them to check CLI help, write local configuration, create host tokens, configure optional metadata, or start the long-running server and host processes. Run each command from the Conda environment or virtual environment where the corresponding package is installed.

This section is a compact reference. For first-time setup order and worked examples, use the Server Deployment and Host Deployment pages first, then return here for command lookup.

Runtime Shell

Runtime commands are typed after the RemoteRF server is already running. Once serverrf --serve opens the server@remoterf: prompt, use help to print the runtime command list for the installed package. These are useful first checks at the prompt.

Complete Command Reference

Use this as the condensed runtime command index. Destructive reset commands are denoted in yellow; use these with caution.

Server State

Use the server-state commands first when you are diagnosing a live deployment. They do not change stored data, and they give you the fastest picture of what the runtime can currently see.

Users and Permissions

Use user commands when you need to inspect who has registered, change an individual user’s access, delete an account, or manage that user’s reservations directly.

• users list prints registered accounts, including username, current permission tier, email, and creation time.
• users manage opens an interactive flow for one username. From there, you can set legacy permission details, delete the user, or add, view, and cancel that user’s reservations.
• users perms prints the underlying permission tables for Users, PowerUsers, and Admins.
• users purge deletes all account records after confirmation.

Account note: Registration emails are recorded but are not currently used for password recovery in the documented user onboarding flow. If a user loses access, the practical recovery path may be to delete or ignore the old account and issue a fresh enrollment code.

Permission note: Group membership is the preferred mechanism for normal class and lab onboarding. Direct per-user management is best saved for exceptions, debugging, manual reservations, or account cleanup.

User Groups and Enrollment Codes

User Groups

User groups are mechanisms used by RemoteRF to scope access without manually configuring each student account one-by-one.

• User Groups: A user group defines the permissions and privileges of its members. It determines which SDRs are accessible to members of the group, the number of reservations each member may hold, and the duration of each reservation.
• Enrollment Codes: An enrollment code is a token that allows a student to self-enroll into a user group without you manually editing their account on the RemoteRF server.

The usual group setup flow is:

1. Run devices list and record the device IDs users should be allowed to use.
2. Run groups create.
3. Enter a clear group name, such as ee101-2026-spring.
4. Enter an explicit device whitelist, such as 0,1,2.
5. Set max_reservation_time_sec for the longest allowed single reservation.
6. Set max_reservations for the maximum concurrent reservations per user.
7. Set lifetime_sec to 0 for no automatic expiration, or to a positive lifetime for temporary cohorts.
8. Run groups list and record the generated group_id.

server@remoterf: groups create
Enter group name (c to cancel): ee101-2026-spring
Devices whitelist (e.g. 0,1,2) (c to cancel): 0,1,2
Max reservation time (sec) [1800] (c to cancel): 3600
Max concurrent reservations [3] (c to cancel): 1
Group lifetime (sec) [0=forever] (c to cancel): 0

Use groups edit when a cohort needs a different whitelist or reservation policy after users have already registered. Use groups csv to export the group table to the machine’s Downloads folder for record keeping.

Note: A user can belong to more than one group. For a device that appears in multiple groups, the server uses the highest applicable reservation duration and concurrent reservation limit for that user.

Enrollment Codes

The usual code-generation flow is:

1. Confirm the target group with groups list.
2. Run codes create.
3. Enter how many codes to generate.
4. Enter the target group_id.
5. Choose the character count per code name, or accept the default.
6. Confirm the generated code names.
7. Set uses per code.
8. Set duration_sec, using 0 only when the code should never expire.
9. Export a copy with codes csv if you need a distribution or audit record.

server@remoterf: codes create
How many enrollment codes? (c to cancel): 25
Group ID to attach codes to? (c to cancel): 1
Characters per code name? [10] (c to cancel): 10
Uses per code? [1] (c to cancel): 1
Duration in seconds? [3600] (0=never expires) (c to cancel): 604800

Use codes delete to delete one code by name or all codes attached to a group ID. Use codes csv to export all current enrollment codes to the machine’s Downloads folder.

Note: Enrollment codes are credentials that allow a user to make an account on the RemoteRF server. Share them only with the intended cohort, and avoid posting a reusable code in a public course page unless that is deliberate.

For field-by-field class guidance, see Class Setup and Generating Enrollment Codes.

Devices, Hosts, and Reservations

Device, host, and reservation commands help you verify what clients will be able to reserve before users arrive.

• devices list prints the device inventory visible to the server runtime.
• devices status prints tunnel-aware device state, which is especially useful when hosts contribute devices.
• hosts status prints the host tunnel status and host-provided device state.
• hosts wipe clears persisted host-directory state and in-memory host tunnel state after confirmation.

Host-state note: The command hosts wipe is for runtime tunnel state, not normal client onboarding. If hosts are still connected, they may repopulate live host state after the wipe.

• reservations list prints reservation IDs, usernames, device IDs, start times, and end times.
• reservations purge deletes all reservation records after confirmation.
• users manage can also add, view, and cancel reservations for one user at a time.

Reservation note: Use reservations list before changing account, group, device, or host state. It is much easier to explain a cleanup action when you have captured the current reservation IDs first.

Destructive Commands

The runtime shell includes several reset commands. Use them deliberately, avoid running them during active labs, and prefer the narrowest command that matches the cleanup target.

Reset note: Use reservations purge when the target is reservation history only. Use db purge only for an intentional full reset of database-backed server state.

Operating Pattern

For a normal class or lab rollout, use this sequence.

After this path works, send users to the Onboarding Users checklist or the end-user Client Documentation, along with the correct server address, network requirement, enrollment code, and Python import pattern.

Next Steps

If the server starts cleanly, devices are visible, groups and codes are ready, and a test client can reserve a device, this can be the end of the server-management path. Navigate to one of the pages below only for the cases where the deployment needs deeper configuration work or diagnosis.