@clawscarf/cli 0.1.0-alpha.1 → 0.1.0-alpha.11

package/README.md

@@ -1,3 +1,120 @@
-# ClawScarf operator
+<a href="https://clawscarf.com"><img src="https://clawscarf.com/clawscarf-mark.svg" alt="ClawScarf logo" width="112" height="112" /></a>
 
-Read the [operator instructions](release/operator.md).
+# ClawScarf
+
+### OpenClaw, ready for your team.
+
+Give your team a shared OpenClaw server—with individual logins, your choice of AI
+models, connected accounts, and execution protected by NVIDIA OpenShell.
+**Self-hosted. Open source. OpenClaw’s own interface.**
+
+[Get started](#get-started) · [Installation guide](https://github.com/clawscarf/clawscarf/blob/main/deploy/deployment/installation.md) · [Releases](https://github.com/clawscarf/clawscarf/releases) · [Contribute](https://github.com/clawscarf/clawscarf/blob/main/CONTRIBUTING.md)
+
+## Get started
+
+```sh
+curl -fsSL https://github.com/clawscarf/clawscarf/releases/download/v0.1.0-alpha.10/install.sh | sh
+export PATH="$HOME/.local/bin:$PATH"
+clawscarf configure
+```
+
+**Choose Team server. Pick a model. Sign in. Start your server.**
+
+The terminal setup walks you through it, downloads the runtime, and opens OpenClaw
+in your browser. Your sign-in becomes the first administrator account. No checkout,
+Docker configuration files or separate OpenClaw installation required.
+
+You’ll need Docker and a model-provider API key. Check the
+[platform requirements](https://github.com/clawscarf/clawscarf/blob/main/deploy/deployment/installation.md) before installing.
+
+<details>
+<summary>Prefer npm?</summary>
+
+```sh
+npm install -g @clawscarf/cli@next
+clawscarf configure
+```
+
+This alternative uses your own Node installation; see the
+[requirements](https://github.com/clawscarf/clawscarf/blob/main/deploy/deployment/installation.md).
+
+</details>
+
+## Make it your team’s workspace
+
+| What you want to do                    | Where to do it                                                                                                            |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| **Start working with an agent**        | Open a chat in OpenClaw. Create and configure agents using its native settings.                                           |
+| **Bring in your teammates**            | Open **People**, create an invitation link, and assign native OpenClaw roles. Administrators can remove access there too. |
+| **Connect Outlook and other services** | Open **Connections**, link an account, and choose which agents can use it. Choose this optional capability during setup.  |
+| **Use your preferred models**          | Choose the provider, model and reasoning level in setup. Run `clawscarf configure` again to change them.                  |
+
+Review the [recipe settings](https://github.com/clawscarf/clawscarf/blob/main/recipes/README.md) and choose your provider and model.
+Usage is billed by your provider; its API key stays outside OpenClaw.
+
+Setup opens **[http://127.0.0.1:18800](http://127.0.0.1:18800)** by default.
+That address is local to your machine. To share the server with teammates, use a
+reachable HTTPS address; the [installation guide](https://github.com/clawscarf/clawscarf/blob/main/deploy/deployment/installation.md#configuration-options)
+covers the public URL and company SSO settings.
+
+OpenShell applies filesystem and network policy to the whole OpenClaw runtime,
+including plugins, shell commands and local tools. Recipes bring login, models and
+optional Connections together in one setup; you keep OpenClaw’s native agents,
+conversations, skills and settings.
+
+## Everyday commands
+
+```sh
+clawscarf status       # Check the server
+clawscarf stop         # Stop it, keeping your data
+clawscarf start        # Start it again
+clawscarf configure    # Change its configuration
+```
+
+The default installation directory is `~/clawscarf-team`. Use
+`--directory ~/another-team` to create or manage a separate installation.
+Chats, files and settings survive stop/start. Closing the terminal leaves the server
+running; Docker must stay running while it is in use.
+
+For automation, the same configuration choices are available as command-line flags
+with `--non-interactive`, and commands support `--json`.
+[CLI reference and examples →](https://github.com/clawscarf/clawscarf/blob/main/deploy/deployment/installation.md#configure-without-prompts)
+
+See [CLI telemetry](https://github.com/clawscarf/clawscarf/blob/main/deploy/deployment/installation.md#telemetry) for usage reporting
+and how to disable it.
+
+## Your server, your team
+
+An installation serves **one trusted team**: separate logins and roles, shared
+execution files and browser accounts. Native roles control application permissions;
+people allowed to run code share the Gateway’s authority. Use separate installations
+for teams that must be isolated from one another.
+
+The Team server recipe enables public web access for agents and shell tools. Operators
+can turn it off; private destinations remain restricted to explicitly configured services.
+Public web access permits sending team data to public services. See the
+[network boundary](https://github.com/clawscarf/clawscarf/blob/main/deploy/openshell/README.md#public-web-access) for enforcement and limits.
+
+Default login and optional Connections use **ClawScarf Cloud**. You can use your own
+OIDC provider and disable Connections to run without those hosted services. Original
+model-provider keys and Connections management credentials stay outside OpenClaw.
+
+See [published releases](https://github.com/clawscarf/clawscarf/releases),
+[security implementation](https://github.com/clawscarf/clawscarf/blob/main/deploy/openshell/README.md),
+[browser support](https://github.com/clawscarf/clawscarf/blob/main/deploy/execution/browser-node/README.md#verified-release-limits)
+and [open work](https://github.com/clawscarf/clawscarf/blob/main/TODO.md) before choosing capabilities. Retained data still needs backups.
+
+## Explore and contribute
+
+- **Using ClawScarf:** [Installation](https://github.com/clawscarf/clawscarf/blob/main/deploy/deployment/installation.md) · [People](https://github.com/clawscarf/clawscarf/blob/main/plugins/access/README.md) · [Connections](https://github.com/clawscarf/clawscarf/blob/main/plugins/connections/README.md) · [Models](https://github.com/clawscarf/clawscarf/blob/main/deploy/models/README.md)
+- **Customizing it:** [Recipes](https://github.com/clawscarf/clawscarf/blob/main/recipes/README.md) · [Packs](https://github.com/clawscarf/clawscarf/blob/main/packs/README.md) · [Runtime architecture](https://github.com/clawscarf/clawscarf/blob/main/runtime/README.md)
+- **Helping build it:** [Contributing](https://github.com/clawscarf/clawscarf/blob/main/CONTRIBUTING.md) · [Development setup](https://github.com/clawscarf/clawscarf/blob/main/scripts/README.md) · [Report a bug](https://github.com/clawscarf/clawscarf/issues)
+
+ClawScarf maintains a small [OpenClaw patch series](https://github.com/clawscarf/clawscarf/blob/main/runtime/openclaw/README.md)
+for selected fixes and optional capabilities. Releases include its exact source provenance.
+
+Built on [OpenClaw](https://github.com/openclaw/openclaw),
+[NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) and
+[LiteLLM](https://github.com/BerriAI/litellm).
+[MIT licensed](https://github.com/clawscarf/clawscarf/blob/main/LICENSE), with [third-party notices](https://github.com/clawscarf/clawscarf/blob/main/THIRD_PARTY_NOTICES.md).
+ClawScarf is an independent project.

package/THIRD_PARTY_NOTICES.md

@@ -12,7 +12,7 @@ the operator, companion and Connections plugin artifacts.
 AGENTS.md is adapted from RawClaw's contributor guide at commit
 [`f37a6e786fdd88857c21bd32140567874e281a8c`](https://github.com/raw-labs/rawclaw/blob/f37a6e786fdd88857c21bd32140567874e281a8c/AGENTS.md),
 with the project owner's authorization. The Connections plugin and companion,
-access service, UI primitives and development checks also extract or adapt donor
+access service, native page flows and development checks also extract or adapt donor
 source and regressions. Their local READMEs identify the incorporated paths and
 deliberate boundary changes.
 The reviewed donor has no top-level license file; do not infer a blanket license
@@ -24,12 +24,21 @@ embedded third-party notices for each extracted component before publication.
 The runtime recipe references pinned OpenClaw and OpenShell artifacts in
 [release/components.json](release/components.json). The access adapter imports
 the published `@openclaw/gateway-client` package. Dependencies and their versions
-are recorded in lockfiles; upstream source is not vendored here.
+are recorded in lockfiles. The [downstream patch series](runtime/openclaw/README.md)
+contains selected source differences and context from MIT-licensed OpenClaw; it is
+not a complete vendored source tree.
 The terminal installer uses MIT-licensed `@clack/prompts` 1.8.1. It is installed
 from the operator lockfile and retains its upstream license with the dependency;
 the installer does not vendor or modify the prompt library.
-The Gateway uses unmodified upstream commit `7bc487d39dc9e059bb9b19ea08152883022f83fe`;
-the [image build instructions](deploy/images/README.md) own source packaging.
+Standalone CLI archives include the unmodified Node.js 24.19.0 executable from
+[official Node downloads](https://nodejs.org/dist/v24.19.0/), verified against the
+SHA-256 pins in [release/components.json](release/components.json). Each archive
+retains Node's complete upstream LICENSE, including its bundled third-party notices,
+at `node/LICENSE`. JavaScript dependencies retain their licenses in `node_modules`.
+Gateway source builds apply the maintained patch series to upstream commit
+`7bc487d39dc9e059bb9b19ea08152883022f83fe`. Release provenance records the
+resulting tree and patch-set digest alongside the exact patches and their intent documents.
+The [image build instructions](deploy/images/README.md) own source packaging.
 OpenClaw's upstream [license](https://github.com/openclaw/openclaw/blob/7bc487d39dc9e059bb9b19ea08152883022f83fe/LICENSE)
 is MIT. NVIDIA NemoClaw's [license](https://github.com/NVIDIA/NemoClaw/blob/main/LICENSE)
 is Apache-2.0. Referencing their architecture is not incorporating their code.
@@ -58,12 +67,10 @@ qualification reports. Debian package copyright files remain under `/usr/share/d
 This initial inventory does not establish complete transitive license review;
 that release requirement remains in [TODO.md](TODO.md).
 
-The Gateway and companion image recipes copy this file and the root [license](LICENSE) verbatim
-to `/usr/share/licenses/clawscarf`. The companion recipe additionally copies the
-incorporated [shadcn notice](ui/shadcn/LICENSE.md)
-there as `shadcn-MIT.txt`. A local runtime rebuild verified the root notices against its build inputs.
-A local companion rebuild also verified the root and shadcn notices against build inputs. Relative
-source links in this file refer to the source checkout, not image filesystem paths.
+The Gateway and companion image recipes copy this file and the root [license](LICENSE)
+verbatim to `/usr/share/licenses/clawscarf`. Native plugin pages use the shared
+[page renderer](plugins/common/native-page.ts) and OpenClaw's host UI components.
+Relative source links in this file refer to the source checkout, not image filesystem paths.
 
 When bundling or adapting software, record its exact version and source, retain its
 license and required notices, and identify modifications where required. Review
@@ -85,7 +92,7 @@ provenance. Paths below are relative to that donor, not files already present he
 | Runtime/defaults and plugin packaging | runtime/openclaw/, deploy/images/hetzner/scripts/install-runtime.sh, plugins/connections/                                           | Reuse defaults, integrity checks and packaging; replace Hetzner, systemd, rootless-engine and host-path assumptions for the selected target.                 |
 | Company login and entry               | src/domains/access/, src/domains/installations/service/openclaw/entry/, src/apps/ingress/, src/composition/ingress.ts               | Reuse OIDC/session/ingress mechanics and native identity semantics; replace organization/admission/placement wiring with standalone ownership.               |
 | Connections                           | plugins/connections/, src/domains/connections/, src/composition/connections/, catalogs/connections/, scripts/connectors-catalog*.ts | Preserve REST tools, Composio adapter, callbacks, account selection and grants; extract required persistence without the fleet control plane.                |
-| Connection account UI                 | src/apps/web/domains/connections/ and its shared visual/form dependencies                                                           | Copy the working flow and visual primitives; remove organization routing through explicit standalone composition.                                            |
+| Connection account UI                 | src/apps/web/domains/connections/                                                                                                   | Adapt the account-management flow to native OpenClaw plugin pages and generated clients; omit the donor web shell.                                           |
 | Model gateway                         | runtime/ai-gateway/, deploy/ai-gateway/, src/composition/ai/ and applicable src/domains/ai/ code                                    | Reuse LiteLLM integration/configuration and tests; replace hosted-source/admission/catalog wiring where needed. Do not recreate the removed inference proxy. |
 | Acceptance                            | tests/ and corresponding helpers for identity, logout, ingress, native roles, connections, model gateway and browser flows          | Transfer regressions with each capability; adapt fixtures and run against the new runtime. Donor success is not new-target acceptance.                       |
 

package/deploy/execution/network/node-ingress.cfg

@@ -32,4 +32,4 @@ frontend native_node
   default_backend native_gateway
 
 backend native_gateway
-  server gateway "host.docker.internal:${CLAWSCARF_NODE_GATEWAY_PORT}" resolvers docker init-addr libc,none
+  server gateway "application:${CLAWSCARF_NODE_GATEWAY_PORT}" resolvers docker init-addr libc,none

package/deploy/execution/network/public-addresses.json

@@ -0,0 +1,24 @@
+{
+  "families": ["0.0.0.0/1", "128.0.0.0/1", "2000::/3"],
+  "excluded": [
+    "0.0.0.0/8",
+    "10.0.0.0/8",
+    "100.64.0.0/10",
+    "127.0.0.0/8",
+    "169.254.0.0/16",
+    "172.16.0.0/12",
+    "192.0.0.0/24",
+    "192.0.2.0/24",
+    "192.88.99.0/24",
+    "192.168.0.0/16",
+    "198.18.0.0/15",
+    "198.51.100.0/24",
+    "203.0.113.0/24",
+    "224.0.0.0/4",
+    "240.0.0.0/4",
+    "2001::/23",
+    "2001:db8::/32",
+    "2002::/16",
+    "3fff::/20"
+  ]
+}

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.11",
   "engines": {
     "node": ">=24.16.0 <25 || >=26.1.0"
   },
@@ -11,6 +11,7 @@
     "node-pg-migrate": "9.0.0",
     "openid-client": "6.8.8",
     "pg": "8.23.0",
+    "posthog-node": "5.52.5",
     "proper-lockfile": "4.1.2",
     "undici": "8.10.2",
     "yaml": "2.9.1",

package/packs/README.md

@@ -26,7 +26,7 @@ It preserves edited and unmanaged files, checks plan integrity and does not repl
 uncertain mutations. Removing an agent remains destructive. Native monitor cleanup
 uses OpenClaw's direct-local password authentication supplied by the
 [runtime launcher](../runtime/README.md); trusted-proxy login remains in place for
-people. Retained installations need the updated runtime image and a Gateway restart.
+people. Use a runtime release containing that launcher contract.
 
 The private runtime helper only inspects packaged source. Individual portable Claws
 can be built with native `openclaw claws build <member-directory> --out <artifact.tgz>`.
@@ -106,8 +106,7 @@ after a Gateway restart, preservation of edited files and rejection of forwarded
 password authentication. The copied fixture omits the model prerequisite; no model
 inference is purchased. Set `CLAWSCARF_TEST_NATIVE_PACKS=1` to run it, optionally
 with `CLAWSCARF_TEST_OPENCLAW` pointing at the packaged runtime launcher. The same
-fixture has passed inside a disposable OpenShell runtime using the pinned upstream
-image plus the updated launcher.
+fixture can also run inside a disposable OpenShell runtime to verify its packaged launcher.
 [Operator binding checks](../tests/packs/connections.test.ts) cover current session,
 exact grants and revision drift. [Transport checks](../tests/packs/transport.test.ts)
 cover UUID dispatch and uncertain failure without replay. The optional
@@ -120,11 +119,5 @@ qualify trusted-proxy removal, external OAuth or connector execution.
 [Execution-target checks](../tests/packs/execution-target.test.ts) use controlled operator
 processes to verify unified runtime dispatch, missing binaries, denied policy
 and runtime replacement. They do not replace live OpenShell qualification.
-A disposable runtime with the image's nftables 1.1.3/libnftnl 1.2.9 dependencies
-loaded an explicit TCP policy: verification accepted its exact process/host/port
-and rejected a different port. This qualifies policy observation and matching;
-it does not establish a successful connector request or application execution.
-
-Run `CLAWSCARF_TEST_NATIVE_PACKS=1 pnpm exec tsx --test tests/packs/native.test.ts`
-for the disposable native test. It writes isolated temporary state and uses the
-pinned OpenClaw dependency installed for the Connections plugin.
+[Network-tool verification](../deploy/images/network-tools/README.md) owns the native
+TCP dependency check; successful policy matching does not establish endpoint reachability.