A customer's reporting service needs a new server. The move involves a service password, an API credential and a multiline signing key. The agent must prepare the destination, update the service and verify a working report. Copying credentials into a conversation would give the model sensitive values it does not need.
OpalSpan's agent-managed secrets let Mech, the built-in agent, and external assistants using OpalSpan Agent CLI carry out that work through private execution. Agents generate or capture arbitrary values, organize them under reusable references, bind exact versions to shell/API work and deliver bytes to authorized files. The conversation receives metadata and safe operation receipts.
OpalSpan organizes the surrounding work across companies, customers and their computers and servers. A useful handback connects the credential changes to the service they were meant to enable: what was installed, which versions were used, what passed and what remains.
The paired desktop and phone films follow one fictional reporting-service move through the actual shared Mech interface. Devices, application utilities, responses and timing are scripted illustrations. They do not perform customer work or measure agent speed.
Start with the job and its boundaries
Give the agent a service outcome, exact targets, recovery position and allowed work:
Move Harbor Studio's reporting service from reports-old to reports-new. Use our trusted management utilities. Prepare a new service password, capture a scoped API credential privately and move the existing signing-key file. Keep all values out of chat. Verify a test report on the new server before retiring the old service credential and source files. Reconcile any uncertain operation before continuing. Leave a clear result and remaining cleanup owner.
Mech can use these tools directly within the controller's existing workspace and device authority. A separate secret-entry screen or one-shot human-permission cycle is not required. The task still needs permission for the actual service, provider, file and retirement operations. Knowing a secret reference does not grant access to it or to another machine.
A reference is the handle; a version identifies the bytes
A secret has an organizational name, a stable opaque reference and a current version. Use names such as harbor/reporting/service-password to help agents find the right record. Put no credential value in the name.
Replacement keeps the reference and increments its version. Rename also updates the version while leaving the bytes unchanged. A binding selects an exact reference/version, so another writer's replacement cannot silently change the credential used by your operation. Read current metadata and reconcile a conflict before making a deliberate update.
An operation ID serves a different purpose: it identifies one intended generation, import, execution or delivery. Reusing it reads the recorded outcome rather than repeating the external work. A credential can serve many operations; an operation ID is not a credential handle.
Generate a password; capture other formats privately
For the reporting service, the agent uses generate_secret to prepare a random password. The default is 32 random input bytes stored as printable Base64. Check the application's accepted length and character rules. This generator does not claim to produce every application's password format.
A key pair, certificate or provider-issued token can instead come from an authorized command or API. Use execute_with_secrets for that work and direct the selected private output into its fresh capture file. The trusted runtime stores the captured bytes and returns a reference, not the response body.
In the film, a fictional pre-existing application utility requests a scoped reporting API credential. Its management credential arrives through a private file binding, and its new token goes into a reserved private output file. That utility represents the customer's integration; it is not an OpalSpan command or a built-in provider-rotation engine.
For a real API, follow that provider's documented authentication, scopes, creation and revocation semantics. An application request may need to parse a response and write only the selected credential bytes. Private transport does not supply missing API rights, confirm a successful rotation or revoke older sessions automatically.
Import the signing key without reading it into the conversation
import_secret captures an existing authorized device file directly into encrypted workspace storage. The agent supplies a path and useful name. It does not open the file through an ordinary model-facing file tool or attach the key to chat.
This works for arbitrary nonempty bytes within the supported size limit, including multiline and binary credentials. For temporary use, a binding with private_file: true gives the child process a protected file path instead of an environment value. That preserves formats which are unsuitable for environment variables, including values containing NUL bytes.
The imported source file remains where it was. Successful import is evidence of stored bytes, not permission to delete the original or proof that a destination service can use them.
Use the secret in the work that needs it
execute_with_secrets resolves versioned bindings privately on the authorized target. A normal binding supplies a child-only environment value. A private-file binding supplies a temporary protected path. The command refers to the environment name or file path; the resolved value stays out of its authored command text.
All stdout and stderr are sealed before ordinary streaming, journals and conversation artifacts, including when the command fails. The agent sees safe state, exit-code and failure metadata. It must not turn a failed sealed command into an ordinary execution that prints the credential for debugging.
In the reporting example, the application's trusted management utility updates the service's password from its environment binding. A subsequent credential replacement updates the stored reference at its expected version. Updating the vault alone does not change a database account or a deployed service: the application change and its verification remain explicit parts of the job.
Copy or migrate bytes for a long-lived service
Ephemeral binding files belong to one execution. A service that must keep a key after the process exits needs a deliberate persistent file or configuration change.
materialize_secret writes exact reference bytes to a new authorized destination and privately reads them back. Existing destination files or links are refused rather than silently overwritten. For existing configuration, use an explicit authorized secret-aware command to update it through the application's normal mechanism.
In the film, Mech imports the signing key from reports-old and materializes it on reports-new. The receipt confirms destination-byte verification. The agent then installs the service credentials and runs a separate non-secret test report. The file check and the service check answer different questions.
Optional retireReference retires the vault record only after verified destination delivery. It does not remove the original imported file, revoke a provider credential or delete a backup. Keep retirement separate until the service and its recovery position are understood.
For an authorized cross-workspace move, an external agent can use the CLI's private local copy/import handoff under each workspace's existing selection and permissions. Verify the destination before retiring the original. Workspace-scoped references themselves do not become cross-workspace access grants.
Recover uncertainty before issuing new work
A connection can fail after a command has run. Read read_secret_operation with the original operation ID and inspect the actual target through a safe check. Completed, not started and uncertain are different outcomes.
The film includes a lost delivery response. Mech reads the original receipt, confirms the stored reference and then resumes the intended job. It does not issue a second API credential because the first response was missed.
A fresh command-capture file stays private at the source during uncertain storage. Once storage is confirmed, remove that exact file through authorized secret-aware work. CLI secrets receipt and secrets cleanup provide the independent local recovery path. Source-file cleanup, temporary binding-file cleanup and retirement of reusable references have separate lifetimes.
Finish with a working service and accurate cleanup
The useful result is a verified report on the new server, with exact credential-reference versions and the original operation receipts. The agent can then carry out the authorized old-service retirement and source-file cleanup, retaining the agreed recovery material.
Deleting a secret clears its live vault ciphertext and records its retired state. Already materialized copies, provider credentials and protected backups remain separate. Record completed cleanup and any remaining owner rather than claiming that every copy everywhere has disappeared.
Where values live—and the trust boundary
Values live in encrypted workspace custody, private runtime transport and the authorized target's process memory, environment or files. Model context receives names, references, versions and safe receipts. Ordinary secret-aware output is sealed before the normal output pipeline.
This is a trusted execution boundary. Root or arbitrary authored code on a trusted target can deliberately copy, transform or transmit a resolved value. OpalSpan secret management is not a sandbox against malicious code or a compromised root account. Choose trustworthy targets and commands, narrow the work and protect application files through their own lifecycle.
New generic records use existing workspace operational access. Migrated legacy records preserve their existing owner/Admin confidentiality. Private storage does not make separate model chats a new confidentiality boundary for unrelated data.
Use it with Mech or your own agent
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 its usable catalog/startup, including the missing-tool-guide fix. Windows and Linux use the capable CLI channel. macOS Intel/ARM are technical previews; the generic-interface release's qualification is build/static-only, without native lifecycle, Apple Developer ID or notarization claims.
Mech receives its actual tool catalog and operating guidance. External agents can discover the installed CLI's capabilities with opalspan capabilities and use opalspan secrets without making a Mech/model call. Existing signed-in profiles remain in place.
Start with the practical Mech guide or the CLI lifecycle and local/remote reference. The verified release evidence records exact versions and platform limits.