Getting started

Applies to the current release: OpalSpan Mech in the browser and the optional Agent CLI 0.17.8 on Windows x64 and Linux x64. The installed CLI command is still forge during the name transition.

Use the table of contents to browse, or enable JavaScript to search the guides and reference pages. Articles remain readable without JavaScript. On a narrow screen, the table-of-contents button opens navigation; Escape closes it.

For a link that follows documentation updates, start at the documentation home or share a stable article address such as https://opalspan.com/docs/guides/diagnostics.html. Links opened within a guide can include /docs/generations/ followed by a snapshot identifier. Those links keep that edition's pages, search and assets together; they do not necessarily show the latest guidance. Check release applicability before following instructions.

1. Set up your workspace

Open OpalSpan to create an account or sign in. Create a workspace or accept an invitation to an existing one. Invitation acceptance is explicit and requires the invited verified email; an email address alone grants no membership.

Returning users with Mech available land in the conversation; Work and other workspace destinations remain available. The read-only Work overview map and accessible list show authorized customers, cases, technicians, devices and live access periods. The map is read-only: a relationship is context, not permission or proof that an agent is making progress.

2. Choose how to work

For the direct route, use Mech in your browser. Describe the work, select the connected device and follow the findings. Mech does not need a CLI installation on your workstation.

If you prefer your own AI assistant, set up the optional OpalSpan Agent CLI on the assistant's Windows or Linux workstation. You supervise installation and authorize its sign-in in the browser; the assistant operates the commands below under your workspace permissions. Mech conversations and their private files do not transfer to the external route.

Follow the Windows or Linux instructions. This installs the agent tool, not the customer device service. Linux also needs a configured protected credential provider before login.

Have the local agent open a new terminal and check the installation:

forge --version
forge login
forge whoami
forge doctor

The compatible forge login command still opens https://forge.readyit.dk automatically. Complete the human authorization there. With several memberships, an interactive terminal offers a workspace chooser. Confirm the workspace shown by whoami before the agent proceeds.

For a named local profile and an explicitly selected workspace:

forge login --tenant support --workspace <workspace-id> --format json
forge whoami --tenant support --format json

Replace <workspace-id> with a workspace UUID returned by OpalSpan. support is an example local profile name, not a workspace ID. JSON mode avoids the terminal workspace prompt; it does not bypass browser authentication, consent or MFA.

3. Make a device available

If the device is already enrolled, continue to the next step. Otherwise use OpalSpan's enrollment journey to choose Windows or Linux and prepare a one-device installer or sharing link.

Tell the recipient whether they are authorizing persistent persistent Daemon access or temporary Rescue. These are different workflows. Running an enrollment package requires local administrator/root authority. Downloading a package alone does not install or enroll a device.

You can create another shared enrollment link while an earlier one remains active. Use Enrollment records → Inspect link to inspect or revoke each link independently; creating a new link does not revoke an older one. The records are server-backed, so refresh or unavailable browser storage does not remove that management path. Secret URLs are revealed once and are not stored in the browser. If installation is delayed, an Admin can use Inspect link → Extend same link to add time to an unused link, even after it expires. The recipient keeps the same URL, code and downloaded installer; consumed or revoked links cannot be reopened. Anyone holding the original URL can use it again after extension; revoke and replace it if it may have reached the wrong person. OpalSpan cannot recover a lost private URL. If a creation response is lost, inspect the records before trying again. Revoking an unconsumed link does not revoke a device already enrolled through it.

4. Connect and check the target

In Mech, choose the connected device in the browser conversation and describe the job. The commands below are for the optional external-agent route only; your AI assistant operates them, not you as a manual CLI workflow.

forge devices list
forge devices show --device <device-id>
forge device connect --device <device-id>
forge exec --device <device-id> --command "hostname"

Use the device UUID from the list, not its display name. Verify the expected machine and platform before making changes. Connect returns an SSH alias for direct ssh or scp use. Access runs as Windows LocalSystem or Linux root, not as the customer's desktop user.

For explicit evidence collection:

forge diagnostics collect --device <device-id> --sections identity,storage --output snapshot.json

The output is a local file containing device information. Store it privately and inspect warnings and cleanup status; see diagnostics.

5. Record work and finish

Use cases for attributed findings, actions, outcomes and next steps. Customer drafts require explicit website review before reviewed copy/download. Sending remains your action outside OpalSpan.

forge device disconnect --device <device-id>

Disconnect releases your control of that device but leaves the persistent Daemon enrolled. forge logout closes the selected profile's connections and removes its remembered login. Neither action deletes case history.

If a command fails, inspect errors and next_actions rather than repeatedly retrying a mutation. Start with troubleshooting.

Table of Contents