# Overdeck GPT Actions Operator — install and configuration

## Deliverables

- `overdeck-gpt-actions-operator-files-v1.zip` — baseline-aware Overdeck source overlay.
- `apply-and-verify-overdeck-gpt-actions-operator-v1.sh` — creates/uses a worktree, applies the overlay, and verifies it fail-closed.
- `overdeck-operator-gpt-actions-v1.yaml` — standalone GPT Actions OpenAPI schema.
- `overdeck-operator-gpt-instructions-v1.md` — standalone Overdeck Operator GPT instructions.

## 1. Apply the implementation

Place the ZIP and apply script in the same directory, then run the script against the Overdeck checkout:

```bash
bash apply-and-verify-overdeck-gpt-actions-operator-v1.sh /home/user/Projects/overdeck
```

If that path is the shared main checkout, the script creates a normal Overdeck worktree automatically. It refuses conflicting edits, applies file modes, runs source validation, the 7 focused operator tests, and `packaging/test-deploy-local.sh`. On a verification failure it restores the worktree's pre-apply state.

The script prints the exact guarded `ship.sh land ...` command when verification succeeds. Run that command, then deploy landed main with:

```bash
bash /home/user/Projects/overdeck/packaging/deploy-local.sh
```

Deployment installs and starts `overdeck-operator.service`, which listens only on `127.0.0.1:8790`, generates `~/.config/overdeck/operator-token` with owner-only permissions, and verifies the authenticated local context endpoint as part of the normal deployment smoke gate.

## 2. Create the public HTTPS route

The service is intentionally not public by default. The implementation includes `packaging/install-operator-tunnel.sh` and `packaging/overdeck-operator-tunnel.service` for an explicit Cloudflare named tunnel.

In Cloudflare, create a named/remotely managed Tunnel and add one published application hostname that points to:

```text
http://localhost:8790
```

Store the tunnel token only in:

```text
~/.config/overdeck/operator-cloudflare-token
```

with mode `0600`, then run:

```bash
bash /home/user/.local/share/overdeck/deploy/packaging/install-operator-tunnel.sh
systemctl --user enable --now overdeck-operator-tunnel.service
```

Do not expose SSH, the Kubernetes API, the Overdeck controller/collector, or repository paths separately.

## 3. Configure the custom GPT

In the GPT editor, add a new Action. Set authentication to **API Key → Bearer**. Use the contents of `~/.config/overdeck/operator-token` as the Action credential; do not put that value in the GPT instructions.

Open `overdeck-operator-gpt-actions-v1.yaml` and replace only:

```text
https://YOUR-OVERDECK-OPERATOR-HOSTNAME
```

with the public HTTPS hostname from the tunnel. Paste that schema into the Action editor.

Use `overdeck-operator-gpt-instructions-v1.md` as the operational portion of the GPT Instructions.

Keep the GPT private during validation. In Preview, the first test should be `getOperatorContext`, followed by a harmless command such as `printf operator-ok` against target `overdeck`.

## 4. What the action can do

The schema contains exactly eight operations: `getOperatorContext`, `exec`, `readFile`, `searchFiles`, `writeFile`, `patchFile`, `startJob`, and `getJob`.

Remote machine selection is resolved from Overdeck's buildbox registry; the GPT cannot submit arbitrary SSH destinations. File mutations are restricted to registered writable worktrees, use SHA-256 compare-and-swap, reject `.git`/ignored/credential-like/symlink paths, and do not mutate the main or deploy clones. Long commands run as transient user-systemd jobs with durable status/output. Every API request receives an operation ID and is recorded in the operator audit ledger.

`exec` intentionally grants high-trust user-level shell authority. The dedicated bearer token is therefore a high-value credential. Destructive-pattern acknowledgement and protected-path rejection are guardrails, not a complete shell sandbox.