Skip to article

Working with OpalSpan Mech

Mech is OpalSpan's built-in browser AI agent for the computer and server work you deliver to your customers. Use it for the device jobs they pay you to handle: investigating faults, configuration, software deployment, maintenance, administration and support. Connect and authorize the target device, then describe the job and the result you need.

Supply the purpose, exact devices and allowed work; review questions, evidence and useful results. Its typed tools use current human controller/workspace/device authority. Selecting a context or model does not grant access/consent/spending. Own-agent CLI is a distinct route with its own conversation and account costs.

Mech also supports internal IT and work on your own devices. Its agent-first tools can maintain company/contact records, link customer and device records, and manage team/workspace settings within your permissions. These supporting tasks need no live device connection. Cases are optional for organizing work and preparing a customer handback.

Read Processing, suppliers and international access before supplying customer data. Hosted Mech and a customer-selected external agent use different provider contracts; separate chats are not confidentiality boundaries.

Conversation and work

Model/reasoning/Plan changes need exact-version confirmation and cannot change an active run. Plan keeps the draft, sends no message and snapshots subsequent runs; it grants no authority. Historical runs retain original model/rate accounting. Missing approved capability fails closed, not silent fallback. Ordinary exec has no arbitrary default execution deadline; bounded admission, explicit deadlines/cancellation, actual access expiry and exact lease renewal remain. Unknown outcome means reconcile the original operation, not replay.

Agent-managed secrets

Use Mech's generic secret tools for a job that needs private credentials: a service password change, an API token, a signing key or a credential move between servers. The agent receives the available tool catalog and operating guidance before its first call. It can perform the lifecycle directly within existing controller, workspace and target authority; a separate entry form or one-shot permission cycle is not required. The actual service/provider/file operation still needs authority.

For example:

Move the reporting service from reports-old to reports-new. Use the trusted management utilities. Generate its new password, capture a scoped API credential privately and import the existing signing-key file. Verify a test report before retiring the old credentials and source files. Keep values out of chat and reconcile uncertain operations before continuing.

Choose the input and private use

  • list_secret_references finds authorized names, opaque IDs, states and current versions. Names organize work; IDs identify records and grant no access.
  • generate_secret stores printable Base64 from random bytes (32 input bytes by default). Check the target application's format. import_secret privately captures existing device-file bytes, including multiline/binary values, without opening them in a model-facing file read. Imports leave their sources intact.
  • execute_with_secrets binds exact reference versions to a child environment. Its binding fields are reference, version, environment_name and optional private_file. A private-file binding supplies a protected temporary path, preserving values unsuitable for an environment variable.

For command/API generation, use a fresh capturePath in a private parent and have the authorized command write the selected returned bytes there. The runtime reserves the file before dispatch; existing final files/links are refused. Use import for existing sources. Provider authentication, scopes and rotation order come from the provider/application's actual contract, not the custody tool.

All stdout/stderr and ordinary artifacts from secret-aware execution are sealed, including failures. Read safe state/exit/failure metadata and use a separate non-secret application check. Keep resolved values out of command text, arguments, chat, attachments and ordinary file-read tools. Ephemeral binding paths last for one execution; persistent service credentials need deliberate materialisation or configuration.

Replace, migrate and verify

Replacement uses replaceReference with current expectedVersion; the stable reference remains and its version increments. rename_secret changes organization and version without changing bytes. Read/reconcile a stale version before choosing a deliberate replacement. A vault update alone does not update a running service.

For a server move, import the authorized source file, then use materialize_secret with destination device, reference, exact version and a new destinationPath. Destination bytes are privately read back. Inspect destination_verified separately from the application's working-service checks. Optional retireReference follows verified byte delivery and retires only the vault source; it does not remove the imported original or revoke provider access. Existing destination files are refused rather than silently overwritten.

Continue safely after a missed response

Keep the original operationId and read read_secret_operation. The same identity reconciles the recorded outcome instead of repeating external work. Inspect actual target state after an uncertain effect before choosing a new operation. A stored reference does not prove a completed service cutover.

Keep a capture source private during uncertain storage. After confirmed capture, remove that exact source through authorized secret-aware work. delete_secret retires live vault ciphertext at its expected version; materialised files, application/provider credentials and protected backups have separate cleanup owners. Report what was verified and what remains.

Values live in encrypted workspace storage, private transport and trusted target processes/files; model context gets metadata and safe receipts. Root or arbitrary authored code can deliberately copy, transform or transmit values: this is not malicious-code isolation. New generic records follow workspace operational access; migrated legacy records retain existing owner/Admin confidentiality.

The independent CLI reference covers local/remote execution and private cross-workspace handoffs. Generic CLI/native interfaces were introduced in Agent CLI 0.39.8 and Host 0.24.17, backed by Bridge 1.21.261. Mech requires Bridge 1.21.262 or later for usable catalog/startup; that release fixes the initial missing tool operating guides. Current releases retain these capabilities. Windows/Linux use capable CLI releases; Mac Intel/ARM remain technical previews with build/static-only qualification, without native lifecycle, Apple Developer ID or notarization claims.

Files and results

Authorized selected attachments enter model input only on submission. Private conversation artifacts and separately gated selected-file analysis do not expose Bridge/customer files generally or make file text an instruction/access grant. Scratch/retained lifetimes differ; no new storage charge is inferred here. Save attributable Case notes/drafts when they help. If a customer handback is useful, review the exact customer text before manual export. No automatic mail, guaranteed repair or measured AI-speed claim. Diagnostics, Automations, CLI and API keep independent scope/consent limits.