# Runmote Custom GPT Knowledge Guide

This file supports two Runmote Custom GPT setup modes for private/direct use:

1. Private fixed endpoint Action API-key mode for testing the
   `https://action.runmote.com/openapi.api-key.json` path.
2. Dynamic direct local session mode for the current per-session local Runmote
   Action setup.

Keep the two modes separate. Never move auth values or recovery steps from one
mode into the other.

The future official shared OAuth Runmote GPT is a separate profile. It uses
ChatGPT account linking and Runmote OAuth authorization, not pasted Action API
keys, dynamic direct local-session values, or OAuth token values.

## Private Fixed Endpoint Action Key

Use this mode when the user mentions fixed endpoint, `action.runmote.com`,
Action API key, RunmoteActionKey, or a revoked fixed endpoint key.

Schema:

```text
https://action.runmote.com/openapi.api-key.json
```

Do not import the OAuth/account-linking schema
`https://action.runmote.com/openapi.json` for this API-key mode. GPT Builder
currently accepts one security scheme per imported Action schema.

Auth:

```text
Authorization: Bearer ACTION_API_KEY
```

Key management:

```text
/settings/action-keys
```

GPT Builder setup:

1. Sign in to Runmote Web.
2. Open `/settings/action-keys`.
3. Create an Action API key and copy it once.
4. In GPT Builder, import `https://action.runmote.com/openapi.api-key.json`.
5. Configure API key auth as the fixed endpoint auth value above.
6. Paste `ACTION_API_KEY` as the key value.
7. Test readiness.

If the key is revoked or expired, create a new Action API key at
`/settings/action-keys` and update the GPT Action auth value. Do not tell the
user to run `runmote action-info --show-token` for this fixed endpoint problem.

Fixed endpoint private testing status:

- The schema document URL imports successfully.
- `inspectRunmoteActionReadiness` works.
- Disabled/noop request acceptance works.
- Revoked keys fail safely with `action_key_revoked`.
- OAuth/account linking is not implemented.
- Real dispatch is not enabled.
- No queue job, relay/client/agent call, runtime mutation, or Codex execution
  occurs.

Do not use these dynamic direct values with fixed endpoint mode:

- `ACTION_SCHEMA_URL`
- `ACTION_AUTH_TOKEN`
- `X-Runmote-Agent-Token`

## Dynamic Direct Local Session

Install Runmote, then run:

```sh
runmote setup-check
runmote bg
runmote action-info --show-token
```

The `action-info --show-token` command prints the values needed by the GPT
Action editor:

- `ACTION_SCHEMA_URL`: import this as the Action schema.
- `ACTION_AUTH_TOKEN`: use this as the API key value.
- Header name: `X-Runmote-Agent-Token`.

Never paste `ACTION_AUTH_TOKEN` into GPT Instructions or normal chat. Treat
`ACTION_SCHEMA_URL` as sensitive while the local session is active.

Do not use fixed endpoint Action API keys, `/settings/action-keys`, or
`Authorization: Bearer ACTION_API_KEY` for the dynamic direct local session.

## GPT Builder Setup

Create or edit a GPT in ChatGPT:

1. Name it `Runmote`.
2. Use a description such as:
   `Connect ChatGPT to your local Runmote session to run Codex, inspect workspace status, and manage code tasks.`
3. Paste `CUSTOM_GPT_INSTRUCTIONS.md` into the Instructions field.
4. Upload this `CUSTOM_GPT_KNOWLEDGE.md` file as Knowledge.
5. Choose one setup mode.
6. For fixed endpoint mode, import
   `https://action.runmote.com/openapi.api-key.json` and use
   `Authorization: Bearer ACTION_API_KEY`.
7. For dynamic direct mode, import `ACTION_SCHEMA_URL`, use API key
   authentication with custom header `X-Runmote-Agent-Token`, and set the
   value to `ACTION_AUTH_TOKEN`.
8. Test with:
   `Check my current workspace status.`

## Safety Model

- The dynamic schema URL and token are per local session/reservation.
- The fixed endpoint Action API key is account-scoped, revocable, and managed
  in Runmote Web settings.
- Stop Runmote when finished:

  ```sh
  runmote stop
  ```

- Runmote capabilities decide whether read-only, network-read, workspace-write,
  commit, push, revert, cleanup, full-diff, or audit actions are available.
- The GPT should call `getSessionCapabilities` before workspace tools.
- The GPT should never commit, push, revert, or clean untracked files unless the
  user explicitly asks and current guard values match.
- OAuth/account linking, Web broker dispatch, and public/shared GPT launch
  remain future work.
- Fixed endpoint private API-key testing is live, but it remains disabled/noop
  and does not execute Codex.

## First Prompt

Use this prompt after importing the schema and setting authentication:

```text
Check my current workspace status.
```