Custom GPT setup

Create your Runmote Custom GPT.

Runmote now tracks three GPT setup profiles. The future official shared Runmote GPT uses OAuth account linking, the private fixed endpoint Action key tests action.runmote.com, and dynamic direct local session mode keeps the current per-session Runmote/Codex flow.

The fixed endpoint is private testing only today. It can import schema, check readiness, and accept disabled/noop requests, but it does not dispatch work, queue jobs, call relay/client/agent services, or execute Codex.

GPT Builder sharing requires a public privacy policy URL. Use https://runmote.com/privacy for the current Privacy and Action Data boundary. OAuth account linking and Connected GPTs are foundation-only until a future milestone.

Download Runmote Download instructions Download knowledge

Which should I use?

Pick one setup profile.

Official shared OAuth GPT: planned account-linking mode for many users. No pasted Runmote keys or local-session token values.

Private fixed endpoint Action key: best for testing the official action.runmote.com path and key revocation behavior.

Dynamic direct local session: best for current local Runmote sessions where ChatGPT talks to the active reservation URL printed by the CLI.

Do not mix the auth models. Shared OAuth users connect with Runmote; fixed endpoint keys come from Web settings; dynamic direct values come from runmote action-info --show-token.

Planned shared mode

Official shared OAuth Runmote GPT

This future premade Runmote GPT is for many users. ChatGPT asks the user to connect Runmote, the user signs in and authorizes account access through OAuth, and Runmote later routes through that user's selected/default trusted device.

The official shared profile uses the fixed Action schema host after OAuth is enabled, but it is not a copy/paste credential flow. If authorization fails, guide the user to disconnect/reconnect Runmote instead of pasting a token. If no device is ready, guide them to install, start, pair, and trust a device.

OAuth foundation only

OAuth is not production-enabled yet. Connected GPTs are visible at /settings/connected-gpts, but they do not enable dispatch, queues, relay/client/agent calls, or Codex execution.

Shared auth path

Connect/sign in with Runmote when ChatGPT asks, then authorize the requested OAuth scopes.

No pasted credentials

Do not ask shared GPT users to paste ACTION_API_KEY, ACTION_AUTH_TOKEN, X-Runmote-Agent-Token, ACTION_SCHEMA_URL, OAuth access values, or device credentials.

Revocation

Users will revoke connected GPT access from Runmote Web Connected GPTs, not by rotating private Action API keys.

Recommended private testing

Private fixed endpoint Action key

Use this when the GPT Action should import the stable Runmote schema host and authenticate with a Runmote Web Action API key.

Schema import: https://action.runmote.com/openapi.api-key.json
Auth value in GPT Builder: Authorization: Bearer ACTION_API_KEY
Key management: Create, copy once, and revoke keys at /settings/action-keys.

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 with the standard fixed endpoint auth value shown above.
6. Test readiness.
7. If a key is revoked or expired, create a new Action API key and update the GPT Action auth value.

Do not use dynamic direct values for this mode.

Do not use ACTION_SCHEMA_URL, ACTION_AUTH_TOKEN, or X-Runmote-Agent-Token with the fixed endpoint Action key.

Current local workflow

Dynamic direct local session

Use this when ChatGPT should talk directly to the local session/reservation printed by your Runmote CLI.

runmote setup-check
runmote bg
runmote bg --profile write --codex-network-access
runmote action-info --show-token

Safe preview mode: runmote bg starts the local session without project-building write permissions.

Project-building mode: runmote bg --profile write --codex-network-access enables the project-building profile for the current project folder.

Schema import: ACTION_SCHEMA_URL
Auth header: X-Runmote-Agent-Token
Auth value: ACTION_AUTH_TOKEN

1. Start Runmote locally from the project folder.
2. Run runmote action-info --show-token.
3. Import ACTION_SCHEMA_URL into GPT Builder.
4. Configure API key auth using custom header X-Runmote-Agent-Token.
5. Paste ACTION_AUTH_TOKEN as the header value.
6. Re-run action-info and update the Action if the local session changes.

Do not use fixed endpoint keys for this mode.

Do not use Authorization: Bearer ACTION_API_KEY or /settings/action-keys for the dynamic direct local session.

Mode comparison

Shared OAuth, fixed endpoint, and dynamic direct stay separate.

Question	Official shared OAuth	Private fixed endpoint	Dynamic direct local session
Schema source	https://action.runmote.com/openapi.json after OAuth is enabled	https://action.runmote.com/openapi.api-key.json	ACTION_SCHEMA_URL from action-info
Auth type/header	OAuth account linking in ChatGPT	Authorization: Bearer ACTION_API_KEY	Custom header X-Runmote-Agent-Token
Where the key comes from	No pasted key; connect/sign in with Runmote	Runmote Web /settings/action-keys	runmote action-info --show-token
Lifetime	Connected GPT account link until disconnected or revoked	Account key until revoked or expired	One local session/reservation
Current status	Planned/foundation only; OAuth not production-enabled	Private testing; disabled/noop only	Supported direct local workflow
Revoked or broken auth	Disconnect/reconnect Runmote or revoke Connected GPT access in settings	Create a new Action API key and update the GPT Action auth value	Run action-info again and update the custom header value

Account state

Sign in when you want account pairing.

Guests can read both setup modes with placeholders. Fixed endpoint Action keys are created after sign-in; dynamic direct schema and token values still come from a local Runmote session.

Sign in

Ubuntu 24.04 sandbox

Verify Codex sandbox readiness.

If project-building mode reports a sandbox issue, run Runmote's sandbox doctor and apply the Ubuntu 24.04 AppArmor/bubblewrap setup only after reviewing it locally.

runmote sandbox doctor
sudo apt update
sudo apt install -y bubblewrap apparmor-profiles apparmor-utils
sudo install -m 0644 /usr/share/apparmor/extra-profiles/bwrap-userns-restrict /etc/apparmor.d/bwrap-userns-restrict
sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict
codex sandbox -- /bin/true

GPT builder

Configure the GPT.

Create or edit a GPT. Open ChatGPT, use Configure mode, name it Runmote, and use the description below.
Paste instructions. Use the downloadable CUSTOM_GPT_INSTRUCTIONS.md.
Upload knowledge. Add CUSTOM_GPT_KNOWLEDGE.md.
Create an Action. For future shared OAuth, import https://action.runmote.com/openapi.json. For private fixed endpoint API-key testing, import https://action.runmote.com/openapi.api-key.json. For dynamic direct mode, import ACTION_SCHEMA_URL.
Configure Action authentication. Shared OAuth uses ChatGPT account linking when enabled. Fixed endpoint uses Authorization: Bearer ACTION_API_KEY; dynamic direct uses custom header X-Runmote-Agent-Token with ACTION_AUTH_TOKEN.
Test it. Ask: Check my current workspace status.

Description

Connect ChatGPT to Runmote to inspect readiness, manage local workspace tasks through dynamic direct mode, and test the private fixed endpoint path.

Fixed endpoint quick values

Schema import: https://action.runmote.com/openapi.api-key.json
Auth value: Authorization: Bearer ACTION_API_KEY
Revoked-key fix: Create a new Action API key at /settings/action-keys and update the GPT Action auth value.

Test prompt

Use this after the schema and matching auth values are configured.

Check my current workspace status.

Copy block

Instructions preview

Download .md

# Custom GPT Instructions

Paste the text below into the Custom GPT Instructions field.

```text
You are Runmote GPT, a coding assistant connected to the user's local machine through Runmote Actions.

These instructions are for private fixed endpoint API-key testing and dynamic
direct local-session setup. They are not the future official shared OAuth
Runmote GPT profile.

Goal:
- Let the user speak normally.
- Convert user requests into the correct Runmote Action calls.
- Do not ask the user to paste Runmote protocol text.
- Before using workspace tools, call getSessionCapabilities.
- Respect capabilities. Do not call disabled tools.

Setup mode boundary:
- If the user asks about the official shared OAuth Runmote GPT, explain that
  shared account-linking instructions are separate and do not ask users to paste
  Runmote keys, local session values, or OAuth token values.
- If the user asks about fixed endpoint, action.runmote.com, Action API key, RunmoteActionKey, or a revoked fixed key, answer with the fixed endpoint setup only: schema https://action.runmote.com/openapi.api-key.json, auth Authorization: Bearer ACTION_API_KEY, and key management at /settings/action-keys.
- If a fixed endpoint Action API key is revoked or expired, tell the user to create a new Action API key at /settings/action-keys and update the GPT Action auth value.
- Never tell the user to run runmote action-info --show-token to fix a fixed endpoint Action API key problem.
- If the user asks about dynamic, direct, local session, ACTION_SCHEMA_URL, ACTION_AUTH_TOKEN, or X-Runmote-Agent-Token, answer with the dynamic direct setup only: runmote action-info --show-token, import ACTION_SCHEMA_URL, configure custom header X-Runmote-Agent-Token, and use ACTION_AUTH_TOKEN as the header value.
- Never mix the two modes. Fixed endpoint private API-key mode does not use ACTION_SCHEMA_URL, ACTION_AUTH_TOKEN, or X-Runmote-Agent-Token. Dynamic direct local session mode does not use Authorization: Bearer ACTION_API_KEY.
- The fixed endpoint private API-key mode is private testing only today: readiness works, disabled/noop request acceptance works, and no Codex execution or real dispatch occurs.

Task routing:
- Use startReadOnlyCodexTaskAsync for inspection, listing, review, or status checks that do not need network.
- Use startNetworkReadCodexTaskAsync for DNS, HTTP, API, package/runtime checks, or running apps that need network but should not intentionally modify files.
- Use startWorkspaceWriteCodexTaskAsync for creating, editing, deleting, or refactoring files.
- Use legacy startCodexTaskAsync only if the needed split endpoint is unavailable.
- If a network task is requested but network-read is unavailable, explain that Runmote must be restarted with Codex network access enabled.

Task execution:
- Create one stable client_request_id per user task.
- Reuse it only when retrying the same task.
- Never start a duplicate task when one is queued or running.
- After starting a task, call waitForCodexTask with timeout_seconds=3.
- If still queued or running, repeat waitForCodexTask with timeout_seconds=3.
- If wait errors or times out, use getCodexTaskStatus or listCodexTasks for the known task.
- A short wait timeout does not mean Codex failed; tasks continue in the background.

Read/network/write rules:
- Read-only tasks must not modify files.
- Network-read tasks should explicitly say: do not intentionally create, edit, delete, stage, commit, or push files.
- For workspace-write tasks, confirm_workspace_write must be true.
- After network-read or write tasks, call getWorkspaceStatus when relevant.
- Report changed and untracked files from workspace status.
- Do not claim files changed unless task result or workspace status confirms it.

Commit and push:
- Do not call commitWorkspaceChanges unless the user explicitly asks to commit.
- Before commit, call getWorkspaceStatus and getWorkspaceCommitPreview.
- Use current guard values from the latest status or preview.
- Never invent guard values.
- Never commit if status changed since review.
- Do not call pushWorkspaceChanges unless explicitly asked and push is enabled.
- Before push, call getWorkspacePushPreview.
- Never force push. Never push tags.
- Never push if the working tree is dirty, behind upstream, or guard values mismatch.

Revert and cleanup:
- Revert and untracked cleanup are destructive.
- Do not call revertWorkspaceChanges or cleanUntrackedWorkspace unless explicitly asked.
- Before cleaning untracked files, call previewUntrackedWorkspace and use the exact expected_untracked_files list.
- Never delete ignored files or untracked directories unless a future capability explicitly supports it.

Safety:
- Do not ask for Action tokens or secrets in chat.
- Do not reveal or repeat tokens, session IDs, tunnel IDs, or internal secrets.
- Treat Codex dangerous bypass as high risk if enabled.
- Warn before broad or destructive write tasks when bypass is enabled.
- Codex network access is not dangerous bypass; it allows DNS/HTTP in the Codex sandbox but keeps workspace filesystem sandboxing.
- Do not perform broad destructive changes unless explicitly requested.
- Ask for clarification if the request is ambiguous or destructive.

Response style:
- Be direct and practical.
- When a task finishes, summarize what was done, status, relevant changed/untracked files, and a suggested next step.
- Do not expose raw tool logs unless needed.
```

Security notes

Never paste ACTION_AUTH_TOKEN or ACTION_API_KEY into GPT Instructions or normal chat.
Treat ACTION_SCHEMA_URL as sensitive while the dynamic direct session is active.
Dynamic URL and token values belong to one local session/reservation.
Fixed endpoint keys can be revoked and replaced at /settings/action-keys.
Stop local Runmote when finished: runmote stop.

runmote stop

Current scope

Fixed endpoint private testing is live for schema import, readiness, disabled/noop request acceptance, and key revocation checks. OAuth/account linking, GPT Store listing, billing, Web broker dispatch, relay/client/agent calls, and Codex execution remain future work.