# Local Computer — Agent-first Staging installation and use

> **Authority:** Staging-only documentation for the currently discoverable macOS Intel Build490 and Linux x64 Build487, dated 2026-10-18. **Not a Production release.** For live version changes, the machine-readable catalog below is authoritative over hardcoded version examples.

## 0. Agent operating contract

You are the **operator**; the human owns device, Client and workspace authorization. Before acting, read the exact current release and actual installed capabilities. Do not infer that website catalog access grants Runtime, Device, OAuth or filesystem authority. Do not create a new Device when troubleshooting an existing one. Do not silently remove, revoke, reset, bypass macOS system prompts, or reuse one environment's credentials with another. Keep personal workspace content local, except for what the user explicitly asks to read/use.

- Human-readable entry: https://staging.localcomputer.inkblocklab.com/help/
- Live machine-readable catalog: https://staging.localcomputer.inkblocklab.com/.well-known/local-computer.json
- Current downloads: https://staging.localcomputer.inkblocklab.com/download/
- Permission and lifecycle distinctions: https://staging.localcomputer.inkblocklab.com/security/
- Initial supported platforms: **macOS Intel x86_64**, **Linux x64 Ubuntu 24.04**. Windows is **not** a current download.

## 1. Discover the correct immutable artifact

```sh
curl -fsSL https://staging.localcomputer.inkblocklab.com/.well-known/local-computer.json -o local-computer-staging-discovery.json
python3 - <<'PY'
import json
d=json.load(open("local-computer-staging-discovery.json",encoding="utf-8"))
assert d["authority"]["scope"]=="staging_artifact_discovery_only"
for key in ("macos","linux"):
    p=d["platforms"][key]
    a=p["artifact"]
    if p["distributionState"]!="staging_candidate" or not a:
        print(key,": no current Staging artifact")
        continue
    print(key,"version",a["version"],"source",a["sourceCommit"])
    print("  URL:",a["url"])
    print("  SHA256:",a["sha256"])
    print("  sidecar:",a["sha256Url"])
    print("  publisher-trusted:",a["signing"]["trustedPublisher"])
PY
```

**Current immutable identity, for independent cross-check:**

| Platform | Build/source | SHA-256 |
|---|---|---|
| macOS Intel | Build490, `9109345177259449cc81c7bd21fa16f2e55b77ac` | `0f095c7066b9112b79f67300fdf3fdb44348931ae79f45f5e7de2efaba746edf` |
| Linux x64 | Build487, `21f9fbcad487cf97e588c30ace7515bc44a7a409` | `a7a2f5507f2209a73153b96e1ef01835d09479ad3e727fd747415769b1c503f7` |

Artifact URLs are exact. Never derive an alternative download host or assume `/latest` names. Current URLs:

- macOS ZIP: https://downloads.staging.localcomputer.inkblocklab.com/macos/2.0.0/build-490/source-9109345177259449cc81c7bd21fa16f2e55b77ac/Local-Computer-Staging-2.0.0-build490-macos-x86_64-0f095c7066b9112b79f67300fdf3fdb44348931ae79f45f5e7de2efaba746edf.zip
- macOS SHA sidecar: https://downloads.staging.localcomputer.inkblocklab.com/macos/2.0.0/build-490/source-9109345177259449cc81c7bd21fa16f2e55b77ac/Local-Computer-Staging-2.0.0-build490-macos-x86_64-0f095c7066b9112b79f67300fdf3fdb44348931ae79f45f5e7de2efaba746edf.zip.sha256.txt
- Linux .tar.gz: https://downloads.staging.localcomputer.inkblocklab.com/linux/2.0.0/build-487/source-21f9fbcad487cf97e588c30ace7515bc44a7a409/Local-Computer-Staging-2.0.0-Linux-x64-build487-a7a2f5507f2209a73153b96e1ef01835d09479ad3e727fd747415769b1c503f7.tar.gz
- Linux SHA sidecar: https://downloads.staging.localcomputer.inkblocklab.com/linux/2.0.0/build-487/source-21f9fbcad487cf97e588c30ace7515bc44a7a409/Local-Computer-Staging-2.0.0-Linux-x64-build487-a7a2f5507f2209a73153b96e1ef01835d09479ad3e727fd747415769b1c503f7.tar.gz.sha256.txt

Use `curl -fL -o <filename> "<exact catalog url>"` for each file and sidecar. Verify integrity **before** extraction:

```sh
# macOS: from directory containing ZIP and .sha256.txt
shasum -a 256 -c <exact-zip-basename>.sha256.txt

# Linux: from directory containing tar.gz and .sha256.txt
sha256sum -c <exact-tarball-basename>.sha256.txt
```

The checksum verifies bytes against the Staging catalog. It is **not an independent publisher signature**. macOS Build490: Apple Development Team `LSWD2R85TY`, **not** Developer ID/notarized. Linux Build487: **unsigned**. Do not call either package a trusted Production installer.

## 2. Install / bootstrap Linux Build487

Supported target: **Ubuntu 24.04 x64**, headless Staging. From the directory containing the verified archive:

```sh
tar -xzf <exact-catalog-linux-tarball>.tar.gz
cd Local-Computer-Staging-2.0.0-Linux-x64
sudo ./install.sh --user "$USER"
```

The product profile installs the CLI at `/usr/local/bin/local-computer-staging`; it does **not** start a fresh Runtime before bootstrap.

1. Identify the exact absolute workspace path requested by the owner. Inspect canonical bootstrap intent:
   `local-computer-staging bootstrap inspect --root <absolute-workspace-path> --json`.
2. Show the **exact** returned path, authority scope and approval digest to the human. Only **after explicit authorization**, run `local-computer-staging bootstrap apply --root <same-path> --approval-digest <exact-digest> --confirmed --json`. Reinspect. Do not fabricate a digest or apply to a different root.
3. Start and inspect using a unique request ID (replace `first-start` only if already used by a different request):

   ```sh
   sudo local-computer-staging service start --request-id first-start --json
   sudo local-computer-staging service reinspect --request-id first-start --json
   sudo local-computer-staging service enable --json
   ```

4. Follow the supported managed Device enrollment/connect output. Actual installed CLI operations include:

   ```sh
   sudo local-computer-staging device enroll --user "$USER"
   sudo local-computer-staging device connect --user "$USER"
   sudo local-computer-staging device status --user "$USER"
   ```

   The first-time **GitHub Device Flow** requires owner approval on the official GitHub page using the code shown by the product. Check the terminal for the *actual* supported sequence; do not repeat enrollment when already enrolled. If overriding the endpoint intentionally, the supported option is `--control-plane https://staging.localcomputer.inkblocklab.com`, never a Production address.
5. Check reported Runtime and HTTPS endpoint readiness before proceeding to the client. A local Gateway health probe for the current configured Staging instance is `curl -fsS http://127.0.0.1:7776/healthz`. The endpoint must remain protected (no anonymous MCP tool listing).

The exact Runtime OS user matters. Do not substitute `$USER` if operating through a different administrative account; use the real installed Runtime user.

## 3. macOS Build490 (Intel)

Download the immutable ZIP and SHA sidecar listed above, verify with `shasum -a 256 -c`, then extract the ZIP with `unzip`. Build490's existing-authorized-Mac **in-place upgrade** and MCP file-read are verified. It was shipped by the signed App's OS-owned release lifecycle, **not** by replacing a live .app directory manually.

- macOS currently has a signed **Local Computer Staging.app**, a fixed App permission authority, and product-owned Runtime lifecycle. Use the **supported installed App / release lifecycle** for upgrades. Do not attempt to simulate a supported `install.sh` or introduce a manual overwrite command for macOS.
- Review macOS security/Gatekeeper prompts yourself. Apple Development signing is not a Developer ID notarization or unconditional first-use approval. First-use on an independent clean Mac has **not** been separately accepted.
- For existing installed App verification, discovery lists:
  `codesign --verify --deep --strict "$HOME/Applications/Local Computer Staging.app"`
  and `curl -fsS http://127.0.0.1:7776/healthz`.
- Screen Recording, Accessibility, Chrome Automation, Documents/Desktop/Downloads privacy grants are separate **macOS OS permissions**. Use the product's `device_status` before a permission test. For protected folders, inspect `includeFolderPermissions=true` only when needed and get exact human consent for any potentially widening test. Do not assume Chrome JavaScript automation works merely because Apple Events is approved.

## 4. Device → ChatGPT OAuth/MCP → first file

After the Runtime is running and the owned protected HTTPS Device endpoint is available:

1. In the ChatGPT account that will actually operate the machine, connect the intended Local Computer Staging MCP endpoint using the supported custom App/connector UI; capability availability depends on the account UI, **not assumed from plan name**.
2. Complete ChatGPT OAuth for the **exact Client / Device / scope / resource**. Device enrollment GitHub authorization is a **separate** approval. Current Linux Build487 device-side pairing confirmation uses a **real interactive terminal** under the Runtime OS user: `local-computer-staging oauth-pair confirm`. Do **not** fake stdin/TTY or claim a current formal Agent confirm API; that capability is planned but not in this build.
3. Once connected, use actual MCP operations in this order: `device_status` → `open_folder` for a *specific existing owner-authorized directory* → `read_file` on a harmless file inside the returned `folderId`. If a folder returns `approval_required`, inspect the exact scope/digest, request the human's explicit approval, then use `grant_resource_access` with the matching digest and `confirmed:true`; retry the original operation. Never silently expand to a parent directory.
4. Confirm the returned content matches the chosen local test file. Use `discover_capabilities` then `inspect_capability` before `execute_capability`; only registered/enabled sources and their real schemas may be invoked. An installed Skill is not the same as a Runtime Provider. For a command use `run_command` or `start_command` **inside an opened folder**, understanding Shell runs with the local OS user's authority, **not** restricted by the file folderId as a sandbox.

Existing acceptance: Linux Build487 Runtime + ChatGPT OAuth/MCP real `read_file` and Mac Build490 installed App + existing ChatGPT MCP real `read_file`. This does **not** mean independent fresh install, every OAuth UI state, arbitrary third-party Provider, or all OS permissions were re-tested for new users.

## 5. Update / restore / revoke / uninstall

- **Update**: re-read the catalog; verify a new candidate ZIP/tarball SHA; compare source/version; choose the platform's **supported product lifecycle**. For Linux inspect installed CLI `service status` and documented release flow; for macOS use the signed Host release lifecycle. Do not overwrite a running Runtime with `cp`, `rm`, or a new cloned checkout.
- **Recover**: inspect `device_status`, local `/healthz`, `service status` on Linux, connection state and the *original request ID*. Continue/reinspect the same durable lifecycle request rather than creating a duplicate. Do not reset Device/OAuth just to clear a failed installation symptom.
- **Client OAuth revoke / disconnect**: remove or terminate the chosen client's grant or transport; this is separate from local files and cloud Device removal. Do not imply a disconnect deletes the Device.
- **Local Device reset**: Linux supports `sudo local-computer-staging device reset-local --user <runtime-user>`. This clears product-owned local identity/state and **does not prove remote revoke**; request explicit approval, and never run against an active Device as routine troubleshooting.
- **Remote Device revoke**: Linux CLI `sudo local-computer-staging device revoke --user <runtime-user> --confirm-revoke` is an explicit remote identity action and may require fresh GitHub approval; separate from local reset/uninstall. Never silently perform it.
- **Linux uninstall**: from the *same verified installer package*, the supported product-owned flow is `sudo ./uninstall.sh`. A successful terminal receipt proves installed product components removed; user workspace and separate remote Device/client records are not automatically deleted. A durable pending uninstall may need the product's precise reinspect/replay protocol; see packaged `deploy/linux/README.md` before action.
- **macOS uninstall**: use the signed App's supported uninstall / authority lifecycle, not arbitrary deletion of `~/.local-computer-staging`, current Gen or OAuth credentials. Obtain exact user approval for any irreversible Device removal.

## 6. Troubleshooting: stop, inspect, act

| Symptom | First check | Do not do |
|---|---|---|
| Artifact mismatch | catalog source/arch/build, bytes, SHA sidecar | run unverified tar/zip |
| Runtime unhealthy | `device_status`, health, product lifecycle request/status | wipe state to pass a check |
| GitHub enrollment unfinished | exact device-flow challenge and terminal output | re-enroll repeatedly or send GitHub token to a third party |
| ChatGPT MCP connection denied | current account connector UI; exact OAuth Client / resource / scope; device-side pairing prompt | bypass pairing with fake interactive terminal |
| Folder `approval_required` | exact directory, digest, owner approval | grant parent/all folders implicitly |
| macOS automation unavailable | capability states in `device_status` | assume Apple Events permission proves Chrome JS execution |
| Unsigned/unnotarized warning | Staging signing facts above | describe the package as trusted/notarized |
| Uninstall vs remote stale Device | inspect remote/local identities separately | treat local cleanup as cloud removal |

**Support:** hello@inkblocklab.com. Include build, OS, source commit, sanitized status and the first failure stage, not tokens, one-time codes or private file contents.

**Data/authority note:** The public `/.well-known/local-computer.json` is *distribution discovery*, not a live Device roster or permission authority. Runtime metadata, credentials, active grants and connected Device capabilities must come from the authenticated device itself.