Skip to content

Commit 916facb

Browse files
Orend11claude
andcommitted
Update the flow image, the quickstart key step, and the known limits
- New docs/oked-flow.png: step 1 shows a branch creation as allowed. - Quickstart step 1: get an OKed API key with oked init. - Linux: support is coming. - Known limits: link the pending-result proposal (NVIDIA/OpenShell#4406) and the originating_process RFC (NVIDIA/OpenShell#4269), tested on 0.1.3. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent f9c2364 commit 916facb

2 files changed

Lines changed: 28 additions & 9 deletions

File tree

‎README.md‎

Lines changed: 28 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ OpenShell supervisor middleware. OpenShell calls it after network policy allows
77
and before OpenShell injects credentials.
88

99
Status: early preview. It covers the GitHub REST API. Tested with OpenShell 0.1.2 and 0.1.3.
10-
You need an OKed account: install `@oked/claude-code` and run `oked init` to get an API key.
10+
You need an OKed API key. Step 1 of the quickstart shows how to get one.
1111

1212
## The problem
1313

@@ -110,28 +110,42 @@ a new review of the proto. NVIDIA says the middleware API is still evolving.
110110
**Start oked-openshell first.** The OpenShell gateway does not start when a registered
111111
middleware is not running.
112112

113-
1. Install: `npm install`.
114-
2. Put the secrets in `~/.config/oked-openshell/env` (`chmod 600`):
113+
1. Get an OKed API key. Install the OKed CLI and pair this machine:
114+
```bash
115+
npm install -g @oked/claude-code
116+
oked init
117+
```
118+
`oked init` shows a pairing code and offers to open your browser. Sign in, and the key goes
119+
to `~/.oked/config.json`. The start script reads it from there. `oked init` also adds the
120+
OKed hook for Claude Code to `.claude/settings.json` in the current folder. To remove that
121+
hook, run `oked uninstall` in the same folder.
122+
2. Install: `npm install`.
123+
3. Put the GitHub token in `~/.config/oked-openshell/env` (`chmod 600`):
115124
```
116-
OKED_API_KEY=... # optional: else the key from `oked init` (~/.oked/config.json)
117125
OKED_GITHUB_READ_TOKEN=... # fine-grained, read-only "Pull requests" and "Metadata"
126+
OKED_API_KEY=... # optional: a key other than the one from `oked init`
118127
```
119-
3. Start the service: `deploy/macos/run.sh examples/github-demo/oked-openshell.yaml`.
128+
4. Start the service: `deploy/macos/run.sh examples/github-demo/oked-openshell.yaml`.
120129
To start it at login, run `deploy/macos/install.sh` (launchd agent `ai.oked.openshell`,
121130
log in `~/Library/Logs/oked-openshell.log`). Run it from a checkout that stays in place,
122131
not from a temporary worktree: the agent runs the code at that path.
123-
4. Register it in `~/.config/openshell/gateway.toml` (see
132+
5. Register it in `~/.config/openshell/gateway.toml` (see
124133
[examples/github-demo/gateway.toml](examples/github-demo/gateway.toml)), then run
125134
`brew services restart openshell`.
126-
5. Attach it in the sandbox policy and apply with `policy set` (`policy update` cannot change
135+
6. Attach it in the sandbox policy and apply with `policy set` (`policy update` cannot change
127136
middleware): `openshell policy set demo --policy examples/github-demo/policy.yaml --wait`.
128-
6. For Claude Code, add the agent instructions to the sandbox. The script shows the lines and
137+
7. For Claude Code, add the agent instructions to the sandbox. The script shows the lines and
129138
asks before it changes anything: `deploy/setup-agent.sh demo`. See
130139
[Agent compatibility](#agent-compatibility).
131140

132141
The registration uses `allow_insecure_transport = true` on loopback. The gateway warns that
133142
extension authentication is off. This is acceptable on one machine.
134143

144+
### Linux
145+
146+
Linux support is coming. The start script and the login agent in `deploy/macos/` need zsh
147+
and launchd, and they are tested on macOS only.
148+
135149
## Config
136150

137151
`oked-openshell.yaml`, checked with zod at startup. An invalid config stops the service.
@@ -216,10 +230,15 @@ receipt ID and latency. The log never has bodies, header values, query values or
216230

217231
## Known limits
218232

233+
- **OpenShell has no "pending" result.** A middleware can only allow or deny, so OKed denies
234+
and the agent sends the request again. The upstream proposal for a pending result is
235+
[NVIDIA/OpenShell#4406](https://github.com/NVIDIA/OpenShell/issues/4406).
219236
- **`git push` is not covered.** It goes to `github.com`, which is L7-opaque: the middleware
220237
never sees it. The demo profile does not allow `git push`. Agents use the REST API.
221238
- **MCP over HTTP is not parsed.** An MCP request is an opaque write, so it needs approval.
222-
- **`originating_process` is always empty** in OpenShell 0.1.2. OKed routes by `sandbox_id`.
239+
- **`originating_process` is always empty** in this OpenShell version (RFC 0009,
240+
[NVIDIA/OpenShell#4269](https://github.com/NVIDIA/OpenShell/issues/4269)). Tested with
241+
OpenShell 0.1.3. OKed routes by `sandbox_id`.
223242
- **No authentication on the extension call** (`allow_insecure_transport`).
224243
- **The retry state is on one machine.** It survives a restart, not a move to another host.
225244
- **Agents differ** (see [Agent compatibility](#agent-compatibility)). An agent that ignores

‎docs/oked-flow.png‎

565 Bytes
Loading

0 commit comments

Comments
 (0)