# OpenCode · native machine identity

Recipe version1.0.0. Add a colored execution-machine label near the bottom left of
OpenCode V2's home and conversation screens while preserving useful native status.

## Get the tested package

- [ZIP package](/downloads/opencode-machine-identity/1.0.0/opencode-machine-identity-1.0.0.zip)
- [Readable manifest](/downloads/opencode-machine-identity/1.0.0/manifest.json)
- [SHA-256 checksums](/downloads/opencode-machine-identity/1.0.0/SHA256SUMS)
- [Full package instructions](/downloads/opencode-machine-identity/1.0.0/README.md)
- [Plain source installer](/downloads/opencode-machine-identity/1.0.0/install.py)
- [Plain source verifier](/downloads/opencode-machine-identity/1.0.0/verify.py)

Check [catalog.json](/catalog.json) for the exact archive hash before extraction.
The archive is self-contained; no npm dependencies or runtime upgrades are installed.

## Decide on this machine

1. Inspect the installed OpenCode version, local instructions, launchers and current
   identity customizations. This package targets V2, not V1. Only Linux/OpenCode2.2.6
   is certified by the initial release; other V2 versions require explicit review.
2. Identify the account running the execution backend. Install as its intended user,
   not into a management account's private home. Never use root to bypass delivery.
3. Obtain the owner's approved hint, optional display role and color. Do not copy
   another host's selection. Example only: hint `HOME ·`, role `agent`, yellow
   `#ffff00` on hostname `workstation` produces `[HOME · workstation agent]`.
4. Confirm this deployment is OpenCode-only. This recipe does not customize Codex,
   change shell prompts/titles, install a backend, or alter models/permissions.

## Download, inspect and preview

Use a private working directory. Fetch the versioned ZIP and its catalog metadata
over HTTPS, compare SHA-256, extract, then read the bundled source and README.
Do not execute downloaded scripts before review. This is not a curl-pipe installer.

```sh
python3 install.py --hint 'HOME ·' --role 'agent' --color '#ffff00'
```

Run from the extracted package as the intended OpenCode user. This dry-run prints
the proposed paths/options, checks the version and refuses conflicting installations.
Supply `--opencode /absolute/path/to/opencode` if it is not on PATH.

## Apply only after authorization

```sh
python3 install.py --hint 'HOME ·' --role 'agent' --color '#ffff00' --apply
```

Only three plugin source files and one explicit identity JSON are installed.
No existing app configuration, auth or sessions are overwritten. A receipt records
created file hashes for safe rollback. Exact reapplication is a no-op. An older or
different identity installation causes a stop rather than duplicate footer labels.

For remote systems, install on the actual execution server in the backend's account.
The TUI receives label/color through typed RPC, not through the terminal's hostname.
Use your normal authenticated remote connection. A remote cross-host deployment
still needs target-specific PTY verification; it is not pre-certified by this package.

## Verify, then keep the receipt

Open home and an idle conversation at80/120columns. Check one label, approved color,
correct execution hostname, model/directory visibility and an unsent draft. No Enter,
model prompt, charge, backend restart, or service disruption is required.

The bundled verifier automates those checks with isolated tmux PTYs. Use its full
README command with your actual expected label, selected model text, idle session
and a visible conversation-title/text marker (to rule out falling back to home).
Save captures privately, not in a public repository. RGB may map to a terminal palette;
report that mapping. Reopen an old TUI if the new plugin has not hot-loaded.

## Roll back or upgrade safely

```sh
python3 install.py --rollback /absolute/path/to/receipt.json
python3 install.py --rollback /absolute/path/to/receipt.json --apply
```

Rollback refuses any installed file whose hash changed, so later user edits are not
discarded. It removes only its own four created files and empty recipe directories.
Keep immutable archives for reproduction and reverify the plugin after OpenCode
upgrades. Missing server identity must show unavailable, never a false local label.

## Upstream references

- [OpenCode V2 plugins](https://opencode.ai/v2/docs/build/plugins)
- [TUI slots and components](https://opencode.ai/v2/docs/build/plugins/cli)
- [Typed RPC](https://opencode.ai/v2/docs/build/plugins/rpc)
- [CLI settings](https://opencode.ai/v2/docs/cli/config)