Skip to article

Device access and enrollment

Applies to CLI 0.17.5 and Daemon 0.16.3 on Windows/Linux x64. See releases for the current platform boundary.

Choose the correct workspace

forge tenant list
forge whoami
forge devices list
forge devices list --all-tenants
forge devices show --device <device-id>

--tenant <profile> selects a local named profile for one command. forge tenant use <profile> changes the remembered default. Profiles keep credentials, connections and SSH aliases separate. --workspace <workspace-id> is a login selector for a real Forge workspace, not a profile name.

The current public service uses workspace-humans-v2: human Admins and Technicians can access and manage ordinary devices across their workspace, including enrollment, sharing, revocation and transfer. Settings, account/role management and invitations remain Admin-only. Machine identities retain their explicit test-workspace, device and run restrictions.

Enroll a device

Enrollment installs persistent elevated access. The Daemon reconnects after reboot without a customer desktop session. Obtain permission for that access before delivering an installer.

The website's enrollment flow is the simplest path. A technician can also prepare one package from the CLI:

forge enrollment create --display-name "Example workstation" --platform win-x64 --out enrollment-package
forge enrollment batch status --batch <batch-id> --wait

Use the batch_id returned by creation to observe enrollment. For Linux, select --platform linux-x64 and deliver the whole private package folder, including its signed sidecars. Follow the generated README.txt; its installation command supplies the code from a private file or prompt rather than embedding it in a command.

Windows recipients run the generated executable and approve elevation. Preserve its generated filename: the one-use enrollment capability is encoded in that filename. Treat the file and filename as confidential. Linux recipients need root authority and systemd for persistent installation.

For the CLI-generated Linux package, run inside its folder on the target:

chmod 700 forge-host
chmod 600 enrollment.code
sudo ./forge-host install < enrollment.code && rm -- enrollment.code

enrollment.code is the generated private input file, not a value to paste into the shell. Retain the signed sidecars while installing. If installation fails, keep the package and inspect the result before retrying.

Creation supports optional --primary-user, --organization, --expires-at <timestamp> or --expires-in-minutes <minutes>. Those user/organization strings are descriptive labels, not customer-directory links.

Enrollment codes are one-device, one-use, expiring and revocable. Observe authenticated device presence after installation; a download or consumed code alone is not proof of a healthy online service.

Share with a recipient who has no account

forge enrollment share create --display-name "Example workstation" --platform win-x64 --out enrollment-share
forge enrollment share status --share <share-id>
forge enrollment share revoke --share <share-id>

Creation writes enrollment-link.txt in a new private output directory and returns a non-secret share ID. Deliver the link through your trusted customer channel, not a public ticket, transcript or log. The link itself is a capability; the share ID alone is not.

  • Windows x64 and Linux x64 are available.
  • The default lifetime is 24 hours; --expires-in-minutes accepts 1–10080 minutes, up to seven days.
  • The recipient needs no Forge account. Possession of the link permits the one-device enrollment; it does not establish the recipient's identity.
  • Repeated downloads do not consume the enrollment. Installation consumes it.
  • Status distinguishes download, consumption and first authenticated online presence. Revocation prevents subsequent use of the pending link.

A link pins a particular verified release. If it expires or its release is unavailable, inspect its status and create a new link if still authorized; do not modify the URL or assume a fallback to a newer package.

For multiple devices, the CLI also accepts a CSV batch; see enrollment command reference.

Connect, execute and transfer

forge device connect --device <device-id>
forge exec --device <device-id> --command "hostname"
forge upload --device <device-id> --source local-file.txt --destination <remote-file-path>
forge download --device <device-id> --source <remote-file-path> --destination downloaded-file.txt

Replace UUID and path placeholders before running. Local paths belong to the technician workstation; remote paths follow the target OS. Quote paths containing spaces.

Connect returns ssh_alias. Use that exact alias for ssh/scp; do not construct it from a hostname. exec, upload and download can establish the required connection if one is not already active.

Remote commands run through PowerShell on Windows and /bin/sh on Linux. Execution is Windows LocalSystem or Linux root. Avoid assuming the signed-in customer's profile, mapped drives, desktop or shell environment is available. exec defaults to a 300-second timeout and accepts --timeout-seconds.

The CLI exposes command output to the caller; protect it as customer data. Bridge's Access History stores metadata, not command text, stdout/stderr or file contents. Forge-managed transfers return a SHA-256 and report transfer metadata.

Exclusive control and interrupted work

One technician identity holds control of a device at a time. Several channels from that identity may coexist, and the identity may control several devices. A busy device requires coordination with the current technician, not repeated connection attempts or a different profile to evade the lease.

Login is the user-visible access lifetime. The CLI maintains short internal grants while authorized; they are not timed support appointments. Loss of relay connectivity ends its channels. Neither commands nor transfers are automatically replayed.

forge device disconnect --device <device-id>
forge logout
forge logout --all

These are alternatives of increasing scope: disconnect one device, log out the selected profile, or log out all remembered profiles. Persistent host-key pins survive disconnect to detect unexpected device identity changes.

Revoking an enrolled device in the website ends its authorization and requests Daemon removal. An offline or unreachable device cannot prove immediate local cleanup; distinguish revocation from observed removal.

Transfer between workspaces

A transfer is an explicit handshake. In the destination profile, create a short-lived acceptance. In the source profile, use that acceptance for the online device:

forge device transfer accept --tenant destination
forge device transfer initiate --tenant source --device <device-id> --acceptance-code <acceptance-code>

The profile names are examples. Keep the returned one-use acceptance code private. Bridge changes ownership only after the Daemon authenticates in the destination. Verify the device there; if a pending transfer must be stopped:

forge device transfer cancel --transfer <transfer-id>

A transfer clears the device's company/contact links; customer records do not move into another workspace. Original case evidence may become unavailable.

Read history in context

Use Access History, device details or an exact access-session page. A session identifies an observed control period, not permission or a command transcript. Old uncorrelated events remain separate rather than being assigned to sessions by guesswork.

Server-observed events and client-reported outcomes have explicit provenance. A disconnected channel does not prove a repair finished or remote cleanup succeeded. Use case notes for that narrative, and API history routes for bounded programmatic reads.