121 lines
6.1 KiB
Markdown
121 lines
6.1 KiB
Markdown
# Napseer CLI
|
|
|
|
Source import for the `nap` operator CLI.
|
|
|
|
This repository is intended to become the canonical source for:
|
|
|
|
- `nap` installer and update UX.
|
|
- Project bootstrap and status commands.
|
|
- Local authenticated MCP wrapper launch/update behavior.
|
|
- Gateway lifecycle commands such as `nap gateway setup`, `repair`, `start`,
|
|
`status`, `logs`, `terminal`, `schedule`, and `vault`.
|
|
|
|
Current state:
|
|
|
|
- `resources/scripts/nap_install.py` owns the versioned, verified, atomic
|
|
runtime bundle installer.
|
|
- `resources/scripts/` contains the public runtime source embedded by the
|
|
backend without behavioral rewrites.
|
|
- `resources/scripts/napseer_mcp_supervisor.py` is the recommended Codex stdio
|
|
entrypoint. It keeps the client transport alive while restarting or reloading
|
|
the generated `napseer_mcp_server.py` worker between requests.
|
|
- Gateway service compatibility remains in the worker while the standalone
|
|
gateway image is built from the public gateway repository.
|
|
- `nap mcp status` and `nap doctor` run a fresh stdio initialization,
|
|
`tools/list`, and authenticated read probe. They deliberately report an
|
|
existing client connection as `not_observable`; a successful fresh probe
|
|
does not claim that a previously opened Codex transport is connected.
|
|
- `nap auth login` stores the shared account session in the user data folder
|
|
(`~/.local/share/napseer/auth.json` on Linux; platform user data directories
|
|
on macOS/Windows). `NAPSEER_USER_DATA_DIR` overrides that location.
|
|
`nap auth login --project` selects a local override. Legacy repository
|
|
credentials remain an explicit override until `nap auth migrate` moves them.
|
|
Gateway identities remain separate in `.napseer/gateway-auth.json`.
|
|
- `.napseer/project.json` is the commit-safe project locator. It contains only
|
|
the schema, API origin, project UUID, and slug; it never contains tokens,
|
|
account or worker identity, encryption state, keys, passphrases, or claim
|
|
links. A fresh clone uses it to attach the intended project.
|
|
- CLI terminal and schedule operations call the running gateway's
|
|
loopback-only, CSRF-protected control API. PTYs therefore live in the daemon
|
|
instead of disappearing when a CLI subprocess exits.
|
|
|
|
Backend discovery publishes the release manifest and exact public source
|
|
revision used for each bundle.
|
|
|
|
Configure Codex and other long-lived stdio clients to launch:
|
|
|
|
```sh
|
|
python3 ~/.local/share/napseer/napseer_mcp_supervisor.py
|
|
```
|
|
|
|
For repositories that may be resumed after Codex opened a different working
|
|
directory, add a trusted project `.codex/config.toml` override with both
|
|
`cwd` and `NAPSEER_PROJECT_ROOT`. MCP processes inherit their launch directory;
|
|
they cannot infer a later client workspace switch over stdio.
|
|
|
|
If `NAPSEER_MCP_WORKER_PATH` points to a stable launcher that loads a separate,
|
|
replaceable runtime, set `NAPSEER_MCP_WORKER_WATCH_PATHS` to the
|
|
`os.pathsep`-separated runtime paths. The supervisor then reloads the launcher
|
|
after any watched runtime is atomically replaced, preserving the same bounded,
|
|
non-replaying request lifecycle used for direct workers.
|
|
|
|
MCP admits at most 32 unfinished requests by default, including cancelled work
|
|
that is still cleaning up. `-32097` means a request was rejected before
|
|
execution; retry after capacity is available. `-32098` means the result
|
|
is uncertain: inspect current state before retrying a mutation. Cancellation
|
|
prevents queued mutations from starting and attempts to release acquired locks.
|
|
It cannot undo a mutation already accepted by the API.
|
|
|
|
The supervisor waits up to 60 seconds for a response, then requests cancellation.
|
|
After 10 seconds without a cleanup acknowledgement, it terminates the worker and
|
|
fails affected requests without replay. Worker input writes have a five-second
|
|
deadline. Override these limits with `NAPSEER_MCP_RESPONSE_TIMEOUT_SECONDS`,
|
|
`NAPSEER_MCP_CANCEL_GRACE_SECONDS`, `NAPSEER_MCP_WRITE_TIMEOUT_SECONDS`, and
|
|
`NAPSEER_MCP_MAX_IN_FLIGHT_REQUESTS`. New source loads only after unfinished work
|
|
has drained. `nap_contract` exposes the runtime's request lifecycle contract.
|
|
These process recovery guarantees require the supervisor; the direct worker is
|
|
for isolated protocol debugging. An already-running older supervisor needs a
|
|
client reconnect after updating.
|
|
|
|
The public operator surface is intentionally small:
|
|
|
|
```text
|
|
nap init | status | doctor | auth | project | files | export | mcp | gateway | update | version | help
|
|
```
|
|
|
|
Authentication has one recovery verb: `nap auth repair`. Normal refresh is
|
|
automatic. `nap gateway repair` creates the separate worker identity once;
|
|
`--replace` is required to replace an existing identity.
|
|
|
|
Agents start only after the user configures an account login or a delegated API
|
|
key. With an account login, `nap init` creates a project owned by that account.
|
|
A committed `.napseer/project.json` always selects the existing project; it
|
|
never causes a replacement to be created. Concurrent refreshes share a bounded
|
|
credential lock, while project overrides remain independent. Network failures
|
|
preserve credentials and offer recovery through `nap auth repair`.
|
|
|
|
`nap auth keys --help` describes scoped API key issuance;
|
|
`nap auth api-key --env VARIABLE_NAME` installs a delegated key privately.
|
|
Keys can expire or be revoked and cannot approve agent decisions. Use separate
|
|
keys when agents need separate identities or permissions.
|
|
|
|
Upgrading from 0.2.x to 0.3.0 requires the current bootstrap once because old
|
|
installers have a fixed list of runtime files. `nap update` on those versions
|
|
rejects the new bundle before changing the active installation. Run:
|
|
|
|
```sh
|
|
curl -fsSL https://api.napseer.com/install | python3 -
|
|
```
|
|
|
|
The bootstrap verifies every asset and switches the runtime atomically without
|
|
changing credentials or project locators. Restart existing MCP client sessions
|
|
after this upgrade; subsequent releases use `nap update` normally.
|
|
|
|
In Bash, run commands as `nap update`, `nap auth login`, and so on. A leading
|
|
`!` is shell history expansion: `!nap update` replays the most recent command
|
|
whose text starts with `nap` and appends `update`; it does not invoke an
|
|
alternate Napseer update mode.
|
|
|
|
The direct wrapper remains the `nap` CLI implementation and an isolated
|
|
protocol-debugging entrypoint.
|