# OpenCode machine identity · 1.0.0

Native bottom-left identity row on OpenCode V2 home and conversation screens.
No shell banner, tmux status strip, source patch or global theme override.
Identity is computed by the execution server and fetched through typed plugin RPC.
This package is OpenCode-only; it does not modify Codex or install an AI runtime.

## Compatibility and inputs

Tested release: OpenCode2.2.6 on Linux. Python3.9+ for the installer. tmux is
optional and used only by verify.py. Newer/different V2 releases need API review
and verification; installer refuses them unless --accept-untested-version is
explicitly selected. V1 is refused. Windows is not supported by this installer;
macOS and non-Linux platforms are unverified. Review upstream V2 documentation.

Identify the human/service account actually running OpenCode. Run the installer
as that account, not root or a management account. Obtain the owner's explicit
hint, optional role, and color selection for this deployment. Inspect any existing
identity plugins first; do not install competing labels. The display role is not
inferred from the SSH username and need not be the OS account name.

## Review, preview, apply

Verify the ZIP checksum against the HTTPS catalog. Extract it into a private
working directory, inspect all source files, and run from that extracted directory.
Do not pipe downloaded scripts directly into a shell.

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

The first command is read-only; the second creates exactly the three plugin files
under `$XDG_CONFIG_HOME/opencode/plugins/ecosystem-machine-identity/` and the
JSON configuration under `$XDG_CONFIG_HOME/ecosystem-field-guide/`. Without XDG
overrides, the config root is `~/.config`. Receipt/hashes are written under
`$XDG_STATE_HOME/ecosystem-field-guide/identity-installs/` (default `~/.local/state`).
XDG destinations must be absolute, non-symlinked, and belong to the current user.

The label is `[<hint> <execution-hostname> <optional-role>]`; a machine whose
hostname is `workstation` shows `[HOME · workstation agent]` for the example.
For a different format, change the approved hint/role, not the server hostname.
If opencode is not on PATH, supply --opencode /absolute/path/to/opencode.

Same files/options are an idempotent no-op. A differing installation or known
older identity customization causes a stop for review, never automatic overwrite.
The installer does not edit cli.json, opencode.json(c), auth, permissions, model
defaults, sessions or services. Global plugin discovery loads the complete package.
An old client may need exit/reopen; do not restart a busy backend merely for UI.

## Verify without billing a model

Check home and an existing idle conversation at80/120columns, exactly one colored
label, normal model/directory information, and persistence while typing a draft.
Do not press Enter. No model request is required. Optional automated checks:

```sh
python3 verify.py --opencode /absolute/path/to/opencode \
  --label '[HOME · workstation agent]' --color '#ffff00' \
  --model-text 'Sol' --session YOUR_EXISTING_IDLE_SESSION_ID \
  --conversation-text 'Visible session title' \
  --output /absolute/path/to/private-verification
```

Substitute actual expected label/model text/session ID and visible conversation
title/text. The verifier requires a conversation marker so a missing session cannot
silently fall back to home and pass. Without --session only
home is tested; that is not a complete conversation verification. Evidence must
be private: captures can contain existing conversation text. Never publish them.
The verifier uses isolated tmux clients/status OFF and only closes its own clients.

For a remote execution backend install the server plugin/config in the account
running that backend. The server-discovered TUI part travels with the plugin;
use the usual authenticated OpenCode --server connection, not a fake local label.
Pass --server and the expected remote label to verify.py. Cross-host remote
attachment has not yet been certified by this release; verify it on the target.

The requested RGB color may be quantized by the terminal. Standard xterm bright
yellow can appear as palette11 or226; base16 colors can be customized by terminal
themes. Confirm visually and report mappings rather than promise exact RGB.
Unavailable RPC shows `[Execution identity unavailable]`, never local-host fallback.

## Change and rollback

Edit only your user-local machine-identity.json for later approved hint/role/color
changes; the UI refreshes about every30seconds. Hostname remains dynamic. After an
OpenCode upgrade, rerun real checks; do not assume the plugin APIs stay identical.

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

Rollback first verifies every installed file hash. If you edited configuration or
source, it refuses; reconcile those changes manually. It removes only the receipt's
four created files and empty recipe directories, retaining the receipt. Original
configuration and sessions were never replaced, so there is nothing to restore.