nexos-connect 0.6.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +124 -79
- package/dist/chunk-M6S2SYK5.js +9 -0
- package/dist/chunk-M6S2SYK5.js.map +1 -0
- package/dist/index.js +24 -7081
- package/dist/index.js.map +1 -1
- package/dist/main-7DXUMUAH.js +11048 -0
- package/dist/main-7DXUMUAH.js.map +1 -0
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -5,37 +5,51 @@
|
|
|
5
5
|
**Point every coding agent you use at the [nexos.ai Gateway](https://workspace.nexos.ai/gateway/api-keys).**<br>
|
|
6
6
|
One key, one model, one command.
|
|
7
7
|
|
|
8
|
-
|
|
9
9
|
|
|
10
10
|
|
|
11
11
|
|
|
12
|
-
[Quick start](#quick-start) · [Usage](#usage) · [Supported agents](#supported-agents) · [Undo](#undo) · [Status](#status) · [Development](#development)
|
|
12
|
+
[Quick start](#quick-start) · [Set up agents](#set-up-agents) · [Start an agent](#start-an-agent) · [Models](#models) · [Usage](#usage) · [Supported agents](#supported-agents) · [Undo](#undo) · [Status](#status) · [Your key](#your-key) · [Development](#development)
|
|
13
13
|
|
|
14
14
|
</div>
|
|
15
15
|
|
|
16
16
|
---
|
|
17
17
|
|
|
18
18
|
Every coding agent keeps its own config file, in its own format, with its own key names.
|
|
19
|
-
**nexos-connect**
|
|
20
|
-
originals, writes the configs, and reports the
|
|
19
|
+
**nexos-connect** puts them on the gateway in one of two ways. **Set up** finds the agents you have,
|
|
20
|
+
shows exactly what it will change, backs up the originals, writes the configs, and reports the
|
|
21
|
+
result — with your key masked. **Start** runs one agent on the gateway for a single session and
|
|
22
|
+
leaves its config alone.
|
|
21
23
|
|
|
22
24
|
- 🔍 **Detects** which agents are installed, and configures only those
|
|
25
|
+
- 📦 **Installs** a missing agent with npm — only after you agree
|
|
23
26
|
- 👀 **Shows the diff first** — `--dry-run` writes nothing at all
|
|
24
27
|
- 🧩 **Merges, never replaces** — your comments, settings and line endings stay
|
|
25
28
|
- ↩️ **Undoable** — originals are backed up, and `restore` puts back what it changed
|
|
29
|
+
- 🔑 **Signs you in** through your browser and creates a key — or takes one you paste
|
|
26
30
|
- 🔒 **Never prints your key** — every line of output is masked
|
|
27
31
|
- 🤖 **Scriptable** — every question has a flag, so it runs unattended
|
|
28
32
|
|
|
29
33
|
## Quick start
|
|
30
34
|
|
|
31
|
-
You need Node.js 20.19 or
|
|
35
|
+
You need Node.js 20.19+, 22.13+ or 24+ and a nexos.ai account. nexos-connect offers to sign you in
|
|
36
|
+
through your browser and creates a key for this machine; you can also paste an API key —
|
|
37
|
+
[get one here](https://workspace.nexos.ai/gateway/api-keys).
|
|
38
|
+
|
|
39
|
+
Install it once, from outside any repository, then run it wherever you like. It installs the
|
|
40
|
+
`nexos-connect` command, and `nexos` as a short alias.
|
|
32
41
|
|
|
33
42
|
```bash
|
|
34
|
-
|
|
43
|
+
cd ~
|
|
44
|
+
npm install -g nexos-connect
|
|
45
|
+
nexos-connect # open the menu: set up agents, start one, change the key or model, restore
|
|
46
|
+
nexos-connect claude # or start Claude Code on the gateway right away, its config untouched
|
|
35
47
|
```
|
|
36
48
|
|
|
37
|
-
|
|
38
|
-
|
|
49
|
+
## Set up agents
|
|
50
|
+
|
|
51
|
+
Choose **Set up agents** in the menu, or run `nexos-connect setup`. Pick a scope, pick your agents,
|
|
52
|
+
sign in or paste a key, choose a model. Before anything is written you see the diff for every file:
|
|
39
53
|
|
|
40
54
|
```diff
|
|
41
55
|
~/.claude/settings.json
|
|
@@ -52,11 +66,9 @@ diff for every file:
|
|
|
52
66
|
}
|
|
53
67
|
```
|
|
54
68
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
codex -c 'model="<selected-model>"'
|
|
59
|
-
```
|
|
69
|
+
The list shows the agents you have not installed too: pick one and it is installed with
|
|
70
|
+
`npm install -g` before it is configured — at user scope, and never on a dry run. Restart an agent
|
|
71
|
+
that is already running so it reads the new config; Claude Desktop needs a full quit.
|
|
60
72
|
|
|
61
73
|
> [!IMPORTANT]
|
|
62
74
|
> OpenAI Codex and GitHub Copilot CLI read the key from the environment. On Windows, setup also
|
|
@@ -68,89 +80,109 @@ codex -c 'model="<selected-model>"'
|
|
|
68
80
|
> . "$HOME\.nexos\env.ps1" # Windows PowerShell, for the current session only
|
|
69
81
|
> ```
|
|
70
82
|
|
|
71
|
-
##
|
|
72
|
-
|
|
73
|
-
| Command | What it does |
|
|
74
|
-
| ------------------------------ | --------------------------------------------------------------------------------------------------------- |
|
|
75
|
-
| `npx nexos-connect` | Set up your agents, interactively |
|
|
76
|
-
| `npx nexos-connect <agent>` | Start one agent on the gateway **without changing its config** — `claude`, `codex`, `opencode`, `copilot`, `pi`, `crush`, `qwen` |
|
|
77
|
-
| `npx nexos-connect restore` | Put back what nexos-connect changed |
|
|
78
|
-
| `npx nexos-connect status` | Report what is configured, and whether it still matches — read-only |
|
|
79
|
-
| `npx nexos-connect forget-key` | Delete the key saved in your system keychain |
|
|
83
|
+
## Start an agent
|
|
80
84
|
|
|
81
85
|
```bash
|
|
82
|
-
#
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
#
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
# No questions asked — for scripts
|
|
89
|
-
npx nexos-connect --harnesses claude-code,codex --key "$NEXOS_API_KEY" --yes
|
|
90
|
-
|
|
91
|
-
# A fresh machine — pick the agents; a missing one is installed, then configured
|
|
92
|
-
npx nexos-connect
|
|
86
|
+
nexos-connect claude # Claude Code on the gateway, for this session
|
|
87
|
+
nexos-connect launch # asks which agent to start
|
|
88
|
+
nexos-connect claude --install # not installed yet? install it first, without asking
|
|
89
|
+
nexos-connect codex -- exec "fix the tests" # anything after -- goes to the agent
|
|
90
|
+
```
|
|
93
91
|
|
|
94
|
-
|
|
95
|
-
|
|
92
|
+
Starting an agent asks for the key and the model the way setup does, then runs the agent with the
|
|
93
|
+
gateway settings passed through flags, environment variables or a private temporary file, deleted
|
|
94
|
+
when it exits. Nothing is written to the agent's config, so there is nothing to restore, and the
|
|
95
|
+
agent's exit code becomes nexos-connect's. An agent that is not installed is offered for install
|
|
96
|
+
first. `--save-key` and `--save-model` keep the key and the model for next time.
|
|
96
97
|
|
|
97
|
-
|
|
98
|
-
|
|
98
|
+
The session stays in the agent's history like any other, and some agents save a `/model` change to
|
|
99
|
+
your own config — the note printed when the agent starts says which.
|
|
99
100
|
|
|
100
|
-
|
|
101
|
-
npx nexos-connect codex -- exec "fix the tests"
|
|
102
|
-
```
|
|
101
|
+
## Models
|
|
103
102
|
|
|
104
103
|
The default model is the nexos.ai router, which picks a model per request. Before the picker opens,
|
|
105
104
|
nexos-connect checks that your key can use it, and offers the router only when that check passes. A
|
|
106
105
|
check that fails, or one you skip with `--no-verify`, leaves it out. After a failed check you choose
|
|
107
106
|
from the models your key can reach; with `--no-verify` you type a model id. The picker lists every
|
|
108
|
-
conversational model the Gateway can serve, including ones it reaches through translation,
|
|
109
|
-
|
|
110
|
-
`--model` exits `2` only when the gateway
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
agent's default for next time.
|
|
107
|
+
conversational model the Gateway can serve, including ones it reaches through translation, except
|
|
108
|
+
those none of your agents can use (Claude Desktop takes only Claude models), and a live probe
|
|
109
|
+
confirms the model works for them. A `--yes` run with no `--model` exits `2` only when the gateway
|
|
110
|
+
rejected the router; anything less certain warns and uses it. Naming the router yourself always
|
|
111
|
+
wins, with a warning only when the gateway rejected it, and the router is never saved as an agent's
|
|
112
|
+
default. Save any other model your key can reach as an agent's default for next time.
|
|
113
|
+
|
|
114
|
+
## Usage
|
|
115
|
+
|
|
116
|
+
| Command | What it does |
|
|
117
|
+
| -------------------------------- | --------------------------------------------------------------------------------------------------------------- |
|
|
118
|
+
| `nexos-connect` | Open a menu: set up, launch, change the key or model, restore |
|
|
119
|
+
| `nexos-connect setup` | Set up your agents, without the menu |
|
|
120
|
+
| `nexos-connect <agent>` | Start one agent on the gateway **without changing its config** — names in [Supported agents](#supported-agents) |
|
|
121
|
+
| `nexos-connect launch [<agent>]` | The same as `nexos-connect <agent>`; with no agent, asks which one to start |
|
|
122
|
+
| `nexos-connect change-key` | Give the configured agents a new key; each keeps its model |
|
|
123
|
+
| `nexos-connect change-model` | Give the configured agents a new model; each keeps its key |
|
|
124
|
+
| `nexos-connect restore` | Put back what nexos-connect changed |
|
|
125
|
+
| `nexos-connect status` | Report what is configured, and whether it still matches — read-only |
|
|
126
|
+
| `nexos-connect login` | Sign in with your nexos.ai account; creates a key for this machine |
|
|
127
|
+
| `nexos-connect logout` | Sign out and clear the saved key from this machine |
|
|
128
|
+
| `nexos-connect forget-key` | Remove the saved key and sign-in from your system keychain, on this machine only |
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
# Preview every change, write nothing
|
|
132
|
+
nexos-connect --dry-run
|
|
133
|
+
|
|
134
|
+
# Set up only this repository
|
|
135
|
+
nexos-connect --scope project
|
|
136
|
+
|
|
137
|
+
# No questions asked — for scripts
|
|
138
|
+
nexos-connect --harnesses claude-code,codex --key "$NEXOS_API_KEY" --yes
|
|
139
|
+
```
|
|
114
140
|
|
|
115
141
|
<details>
|
|
116
142
|
<summary><b>All options</b></summary>
|
|
117
143
|
|
|
118
|
-
| Option | Effect
|
|
119
|
-
| --------------------- |
|
|
120
|
-
| `--harnesses <ids>` | Agents to set up
|
|
121
|
-
| `--key <key>` | nexos.ai API key. Falls back to `$NEXOS_API_KEY`, then the saved key, then a prompt
|
|
122
|
-
| `--save-key` | Save the key in your system keychain for future runs
|
|
123
|
-
| `--model <id>` | Model every agent uses. Falls back to `$NEXOS_MODEL`, then the saved default, then a picker
|
|
124
|
-
| `--save-model` | Save the model as each agent's default
|
|
144
|
+
| Option | Effect |
|
|
145
|
+
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
146
|
+
| `--harnesses <ids>` | Agents to set up, by their ids in [Supported agents](#supported-agents) |
|
|
147
|
+
| `--key <key>` | nexos.ai API key. Falls back to `$NEXOS_API_KEY`, then the saved key, then a prompt |
|
|
148
|
+
| `--save-key` | Save the key in your system keychain for future runs |
|
|
149
|
+
| `--model <id>` | Model every agent uses. Falls back to `$NEXOS_MODEL`, then the saved default, then a picker |
|
|
150
|
+
| `--save-model` | Save the model as each agent's default |
|
|
125
151
|
| `--install` | Install a not-installed agent with `npm install -g`. Setup installs the ones you pick in the list; starting an agent installs the named one first. `--yes` never installs |
|
|
126
|
-
| `--scope <scope>` | `user` (default — your home directory) or `project` (this directory only)
|
|
127
|
-
| `-y`, `--yes` | Answer every question with its default and write without asking
|
|
128
|
-
| `--dry-run` | Show the diffs and write nothing
|
|
129
|
-
| `--no-verify` | Skip the gateway checks — key, model list and router — e.g. when offline. Without a check, the router is not offered
|
|
130
|
-
| `--backup-dir <path>` | Where originals are copied. Default `~/.nexos/backups/`, or `./.nexos-backup/` for a project
|
|
131
|
-
| `--verify` | With `status`: check the resolved key against the gateway once
|
|
132
|
-
| `--json` | With `status`: print the report as one JSON object
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
152
|
+
| `--scope <scope>` | `user` (default — your home directory) or `project` (this directory only) |
|
|
153
|
+
| `-y`, `--yes` | Answer every question with its default and write without asking |
|
|
154
|
+
| `--dry-run` | Show the diffs and write nothing |
|
|
155
|
+
| `--no-verify` | Skip the gateway checks — key, model list and router — e.g. when offline. Without a check, the router is not offered |
|
|
156
|
+
| `--backup-dir <path>` | Where originals are copied. Default `~/.nexos/backups/`, or `./.nexos-backup/` for a project |
|
|
157
|
+
| `--verify` | With `status`: check the resolved key against the gateway once |
|
|
158
|
+
| `--json` | With `status`: print the report as one JSON object |
|
|
159
|
+
| `--key-name <name>` | Name of the key created when signing in. Default `nexos-connect (<hostname>) <date and time>` |
|
|
160
|
+
| `-h`, `--help` | Show the full reference |
|
|
161
|
+
| `-v`, `--version` | Show the version |
|
|
162
|
+
|
|
163
|
+
The menu, `change-key` and `change-model` never take `$NEXOS_API_KEY` or `$NEXOS_MODEL` as an
|
|
164
|
+
answer; only `--key` and `--model` do.
|
|
165
|
+
|
|
166
|
+
Exit codes: `0` done · `1` an agent failed, or could not start · `2` usage error · `130` cancelled.
|
|
167
|
+
Once an agent has started, its own exit code passes through. Run `nexos-connect --help` for the full
|
|
168
|
+
reference.
|
|
136
169
|
|
|
137
170
|
</details>
|
|
138
171
|
|
|
139
|
-
> [!TIP]
|
|
140
|
-
> `npm install -g nexos-connect` installs the `nexos-connect` command, and `nexos` as a short alias.
|
|
141
|
-
|
|
142
172
|
## Supported agents
|
|
143
173
|
|
|
144
|
-
| Agent
|
|
145
|
-
|
|
|
146
|
-
| Claude Code
|
|
147
|
-
|
|
|
148
|
-
|
|
|
149
|
-
|
|
|
150
|
-
|
|
|
151
|
-
|
|
|
152
|
-
|
|
|
153
|
-
|
|
|
174
|
+
| Agent (`--harnesses` id) | Start with | User scope | Project scope |
|
|
175
|
+
| ------------------------ | ---------- | --------------------------------------------------------------------------- | -------------------------------- |
|
|
176
|
+
| Claude Code | `claude` | ✅ `~/.claude/settings.json` | ✅ `.claude/settings.local.json` |
|
|
177
|
+
| Claude Desktop | — | ✅ `Claude-3p/` in its app data folder | — |
|
|
178
|
+
| OpenCode | `opencode` | ✅ `~/.config/opencode/opencode.json` + `~/.local/share/opencode/auth.json` | ✅ `opencode.json` |
|
|
179
|
+
| Pi | `pi` | ✅ `~/.pi/agent/models.json` | — |
|
|
180
|
+
| Crush | `crush` | ✅ `~/.config/crush/crush.json` | ✅ `.crush.json` |
|
|
181
|
+
| Qwen Code | `qwen` | ✅ `~/.qwen/settings.json` | ✅ `.qwen/settings.json` |
|
|
182
|
+
| OpenAI Codex | `codex` | ✅ `~/.codex/config.toml` + `~/.nexos/env` | — |
|
|
183
|
+
| GitHub Copilot CLI | `copilot` | ✅ `~/.nexos/env` | — |
|
|
184
|
+
|
|
185
|
+
Every agent but Claude Desktop can be started with `nexos-connect <name>`, and installed with npm.
|
|
154
186
|
|
|
155
187
|
> [!WARNING]
|
|
156
188
|
> A project-scope config holds your API key **inside your repository**. Make sure the file is
|
|
@@ -159,7 +191,7 @@ Run `npx nexos-connect --help` for the full reference.
|
|
|
159
191
|
## Undo
|
|
160
192
|
|
|
161
193
|
```bash
|
|
162
|
-
|
|
194
|
+
nexos-connect restore
|
|
163
195
|
```
|
|
164
196
|
|
|
165
197
|
Every setting nexos-connect wrote goes back to what it was before the first run; everything you added
|
|
@@ -169,7 +201,7 @@ for a project).
|
|
|
169
201
|
## Status
|
|
170
202
|
|
|
171
203
|
```bash
|
|
172
|
-
|
|
204
|
+
nexos-connect status
|
|
173
205
|
```
|
|
174
206
|
|
|
175
207
|
`status` is read-only and never writes. It reports the key, the env file, the backup folders and the
|
|
@@ -187,10 +219,23 @@ when set, else the canonical `https://api.nexos.ai`.
|
|
|
187
219
|
|
|
188
220
|
Your key is never printed in full — not in diffs, reports or gateway errors. Save it with `--save-key`
|
|
189
221
|
and later runs offer it from your system keychain (macOS Keychain, Windows Credential Manager, or the
|
|
190
|
-
Secret Service on Linux); `
|
|
222
|
+
Secret Service on Linux); `nexos-connect forget-key` removes it.
|
|
223
|
+
|
|
224
|
+
`nexos-connect login` — or choosing to sign in when setup asks for a key — opens your browser on
|
|
225
|
+
nexos.ai, creates a key named after this machine, and keeps it in the system keychain, where you stay
|
|
226
|
+
signed in. When that key is rejected later, the next run creates a new one. While you are signed in, every
|
|
227
|
+
key question also offers a new key, without the browser.
|
|
228
|
+
|
|
229
|
+
A new key replaces the saved one only after you agree (`--yes` replaces only a key the gateway
|
|
230
|
+
rejected), and nexos-connect never deletes a key: the old one stays active until you delete it at
|
|
231
|
+
[nexos.ai](https://workspace.nexos.ai/gateway/api-keys). `nexos-connect logout` signs you out and clears
|
|
232
|
+
the saved key from this machine; `forget-key` clears this machine without signing you out at nexos.ai.
|
|
233
|
+
`--key` and `$NEXOS_API_KEY` remain for CI and machines without a browser or keychain.
|
|
191
234
|
|
|
192
235
|
Setup still writes the key in plain text to each agent's config and to `~/.nexos/env` (and, on
|
|
193
236
|
Windows, to your user environment), where the agents read it; a saved key does not change that.
|
|
237
|
+
Starting an agent hands it over through the environment or a private temporary file, deleted when
|
|
238
|
+
the agent exits.
|
|
194
239
|
|
|
195
240
|
## Development
|
|
196
241
|
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../src/cli/exit-code.ts"],"sourcesContent":["export const EXIT_CODE = { ok: 0, failed: 1, usage: 2, cancelled: 130 } as const\n\nexport type ExitCode = (typeof EXIT_CODE)[keyof typeof EXIT_CODE]\n\n/** `nexos-connect <agent>` passes the started agent's own exit code through unchanged. */\nexport type AgentExitCode = number\n"],"mappings":";;;AAAO,IAAM,YAAY,EAAE,IAAI,GAAG,QAAQ,GAAG,OAAO,GAAG,WAAW,IAAI;","names":[]}
|