Codex
Nexting Devices integration
Step into Codex from physical hardware
Keep sessions and credentials on a trusted Host. Send only one-time decisions and live state to nearby keys, LEDs, or a display.
What you can do today
This is the frozen, testable public surface between Codex and Nexting Devices today.
How it works
Agent asks
Codex reaches a one-time action that needs user judgment.Trusted Host filters
The Host checks request type, choices, and risk fields, then sends only an eligible bounded summary.Hardware answers
The user operates a developer-mapped physical control; the device returns only the allow or deny choice for the current request.Agent continues
The Host authoritatively commits the answer, resolves hardware state, and the same Agent session continues.
| Developer-mapped physical control | Mapping | User outcome |
|---|---|---|
| Your mapped confirm control | approval/1 → allow | Approve the current one-time request |
| Your mapped cancel control | approval/1 → deny | Deny the current one-time request |
| LED / screen row | status/1 → slot | See one volatile Agent state |
Why this connection is trustworthy
Trust comes from LE Secure Connections and encrypted GATT, local Host credential isolation, minimum disclosure, and expiry, replay, and single consumption checks. Developer Reference Just Works is encrypted pairing; production still needs authenticated application identity.
| Control | Nexting implementation boundary |
|---|---|
| BLE LE Secure Connections | The local device link uses BLE LE Secure Connections and encrypted GATT permissions for control traffic. |
| opaque request ID | Agent credentials and internal account or session routes stay on the trusted Host; firmware receives bounded profile data such as an opaque request ID. |
| single consumption | The Host checks authorization, expiry, sequence/revision, duplicate or replay state, and single consumption. |
| state and partial-frame clearing on disconnect | Disconnect, reboot, a new bond, reset, or Host revocation clears the applicable volatile state and partial frames. |
| voice/1 | voice/1 controls the Host microphone lifecycle and never carries audio bytes or transcripts. |
| Just Works | Developer Reference Just Works pairing encrypts the link but production needs authenticated application identity and signed firmware. |
Technical contract
The device speaks BLE only to a Nexting Host. The Host translates a bounded approval into a Codex session action. Firmware stores no Agent credentials and parses no prompts.
Official integration surface
Nexting's rich integration is built on the official Codex App Server for threads, approvals, and streamed Agent events; the higher-level Codex SDK is aimed at server-side automation. App Server stays local to the user's computer. The authenticated Nexting Bridge relays minimum events instead of exposing App Server to the public internet.
| App Server request | Eligible for approval/1 | Allow choice | Deny choice |
|---|---|---|---|
| item/commandExecution/requestApproval | Only explicit accept / decline, a meaningful command, and no elevated fields | {"decision":"accept"} | {"decision":"decline"} |
| item/fileChange/requestApproval | Only one-time choices, a meaningful reason, and no grantRoot | {"decision":"accept"} | {"decision":"decline"} |
| item/permissions/requestApproval · item/tool/requestUserInput · mcpServer/elicitation/request | Never; keep on phone or desktop | — | — |
Approval exchange
Host → device {"v":1,"t":"present","id":"3bb7","sum":"Apply patch to 3 files?","opt":["allow","deny"],"ttl":30000}
device → Host {"v":1,"t":"answer","id":"3bb7","ch":"allow"}
Host → device {"v":1,"t":"resolved","id":"3bb7","r":"answered"}A firmware key handler calls nexting_device_state_choose(&approval, NEXTING_DEVICE_CHOICE_ALLOW, now_ms(), &answer), then encodes and notifies. The SDK owns countdown, one-second retry, and resolution state.
Status display
The device declares one to eight statusSlots in Device Info. Slots absent from a frame are empty; disconnect clears all state.
Status frame
{"v":1,"t":"status","agents":[{"slot":0,"state":"thinking","label":"fix login bug"}]}Complete physical control surface
These seven profiles ship together in the SPEC, shared vectors, C99, and JavaScript reference. Devices report generic physical events; the official App's Agent adapter still decides whether a key means fork, send, fast, or another action.
| Profile | Direction | What hardware can do | Messages |
|---|---|---|---|
| navigation/1 | Both | Multi-option navigation and selection | nav_present · nav_move · nav_select · nav_resolved |
| keys/1 | Both | Generic key events, labels, and lighting | keymap · key_event |
| rotary/1 | Both | Session and model switching | rotary_map · rotary_event · rotary_press |
| voice/1 | Both | Start, stop, or cancel push-to-talk | voice_event · voice_state |
| text/1 | Host → device | Render bounded plain text | text |
| usage/1 | Host → device | Show model and usage counters | usage · usage_clear |
| config/1 | Both | Atomically update keys, lighting, and display preferences | config · config_result |
Key and rotary events
{"v":1,"t":"key_event","slot":3,"event":"press","seq":18}
{"v":1,"t":"rotary_event","slot":0,"delta":1,"seq":19}
{"v":1,"t":"voice_event","event":"start","seq":20}seq lets the Host discard replayed or out-of-order input. Device Info must declare the key, rotary control, and profile first; the Host sends and accepts no undeclared profile.