s-gw

<p align="center">
  <img src="assets/icons/s-gw-128.png" alt="s-gw" width="96" height="96">
</p>

<h1 align="center">s-gw</h1>

<p align="center">
  <strong>Local credential control for coding agents.</strong><br>
  Approve bounded actions locally. Keep raw credentials out of model context and tool output.
</p>

<p align="center">
  <a href="https://github.com/sgateway/s-gw/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/sgateway/s-gw/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://www.npmjs.com/package/@s-gw/s-gw"><img alt="npm" src="https://img.shields.io/npm/v/%40s-gw%2Fs-gw"></a>
  <a href="LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-2ea44f"></a>
  <img alt="Node.js 20+" src="https://img.shields.io/badge/Node.js-20%2B-43853d">
  <a href="https://s-gw.com"><img alt="Website: s-gw.com" src="https://img.shields.io/badge/website-s--gw.com-22c55e"></a>
  <a href="https://github.com/sgateway/s-gw/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/sgateway/s-gw?style=social"></a>
  <img alt="Project status: preview" src="https://img.shields.io/badge/status-preview-f59e0b">
</p>

<p align="center">
  <a href="https://s-gw.com">Demo</a> ·
  <a href="https://github.com/sgateway/s-gw/releases">Downloads</a> ·
  <a href="#quick-start">Quick start</a> ·
  <a href="docs/README.md">Documentation</a> ·
  <a href="SECURITY.md">Security</a> ·
  <a href="CONTRIBUTING.md">Contributing</a>
</p>

[![s-gw demo](docs/images/s-gw-overview.png)](https://s-gw.com)

Stop handing raw credentials to coding agents. s-gw gives agents typed handles, asks you to approve bounded local actions, resolves the credential inside a constrained process on your machine, and returns sanitized output instead of secret values.

> [!IMPORTANT]
> s-gw is an early preview. Storage formats and interfaces may change, Windows support is still experimental, and the project has not completed an independent security audit. Do not treat it as a replacement for endpoint security or a hardened enterprise secrets platform yet.
>
> The TypeScript broker, clients, and documentation in this repository are Apache-2.0 licensed. Distributed packages also contain a proprietary compiled Rust execution core whose source is maintained separately.

## The Short Version

- **Agent sees:** `s-gw:credential:prod-readonly`
- **You approve:** agent, command, handle, environment binding, working directory, and target
- **s-gw runs:** the command locally with the credential injected only into that child process
- **Agent receives:** sanitized output, audit evidence, and no raw secret

If s-gw helps your agent workflow, [star the project](https://github.com/sgateway/s-gw/stargazers). It makes the preview easier for other developers to find.

## See It In Action

The local console shows the approval queue, credential inventory, policy state, usage flow, and activity history without exposing secret values.

![s-gw local console overview](docs/images/s-gw-overview.png)

Public demo: [s-gw.com](https://s-gw.com).

## What It Does

| Govern | Approve | Execute | Audit |
| --- | --- | --- | --- |
| Turn secrets into typed local handles that agents can reference safely. | Review the requesting agent, handle, command, environment binding, working directory, and target before access is granted. | Inject the credential only into the approved child process on the same machine. | Record request, approval, execution, policy, and destination evidence without storing returned raw secrets. |

## Why Teams Use It

- **Local custody:** raw values stay in macOS Keychain, Windows Credential Manager, 1Password, or the encrypted local ledger.
- **Action-scoped access:** grants bind to the agent, handle, command, environment variable, working directory, target, approval mode, and optional time window.
- **Useful handles:** agents can request real work with stable handle names instead of seeing keys, passwords, tokens, or SSH material.
- **Output sanitization:** command output is scanned before it returns to the agent, replacing detected credential values with handles.
- **Agent-aware setup:** Codex, Claude Code, Cursor, OpenCode, Gemini CLI, GitHub Copilot, VS Code, and other MCP clients get profile-specific configuration.
- **Local operator UI:** the macOS app, menu helper, CLI, and web console show approvals, credential inventory, policies, usage flow, activity, and audit history.

## How It Works

```mermaid
flowchart LR
    A["Coding agent"] -->|"Handle + action request"| G["s-gw local gateway"]
    G --> U["Local approval"]
    U --> R["Constrained runner"]
    K[("Keychain / Credential Manager / encrypted store")] --> R
    R -->|"Sanitized output"| G
    G --> A
```

The agent never needs the unlock passphrase or raw credential. Approval is scoped to the requested operation rather than granting general access to the store.

## Core Surfaces

| Surface | Purpose |
| --- | --- |
| `s-gw` CLI | Setup, credential enrollment, approvals, policies, agent snippets, guard mode, and diagnostics. |
| `s-gw-mcp` / `s-gw mcp` | Stdio MCP server for agent-facing handle discovery and request creation. |
| Native macOS app | Approval queue, credential inventory, policy rules, usage flow, activity, and audit review. |
| Menu-bar helper | Fast visibility into pending approvals and local daemon status. |
| Local web console | Browser-accessible fallback UI bound to `127.0.0.1`. |
| Guard mode | Launch agents with credential-looking environment values replaced by s-gw handles. |

## Quick Start

The public npm package is the recommended installation path on macOS, Windows 10/11, and Linux. Install Node.js 20 or newer, then run:

```bash
npm install -g @s-gw/s-gw
s-gw setup
s-gw status
```

On Windows, run the same commands in PowerShell. Windows support is preview software: it uses the TypeScript execution path and includes the PowerShell client, tray helper, and local web console.

For an Apple Silicon Mac desktop bundle, [GitHub Releases](https://github.com/sgateway/s-gw/releases) also provides a self-contained `s-gw.dmg`. Drag `s-gw.app` to **Applications**, then open it and complete setup. The app includes its own Node runtime, CLI, MCP server, native helpers, and menu-bar helper; it does not require Node.js or npm on the host. Setup is intentionally blocked until the app is in `/Applications` or `~/Applications`.

An unsigned DMG requires a Gatekeeper override. Use the npm installation above instead if you do not want to use that override.

The public source builds the TypeScript compatibility path. Building the native macOS surfaces also requires a Swift toolchain. Maintainer release builds additionally require access to the private Rust core checkout.

The Apple Silicon Mac DMG is a self-contained desktop alternative. Published macOS DMGs are either Developer ID signed and notarized or explicitly documented as unsigned; unsigned builds require a Gatekeeper override but retain the standard release tag and update path. Local `npm run build:installers` output is ad-hoc signed for local verification. The npm package is the primary install and includes the native app, menu helper, Keychain helper, metadata-only Keychain inspector, and Rust core for Apple Silicon Macs. Linux and Windows use the TypeScript execution path when a matching native core is not packaged. Intel Macs must build the native Keychain and desktop surfaces from source for now; packaged arm64-only helpers are rejected before launch.

```bash
git clone https://github.com/sgateway/s-gw.git
cd s-gw
npm ci
npm run build
npm link
s-gw setup
s-gw status
```

`s-gw setup` generates local unlock material, stores it in the operating system credential store, initializes the encrypted ledger, starts the local UI surfaces available on the current platform, and safely connects detected supported agents. The self-contained macOS app runs its bundled runtime in place; npm installs copy the thin app into `/Applications`, falling back to `~/Applications` when needed. Setup backs up existing agent config, preserves unrelated settings, installs the packaged s-gw skill where supported, and reports per-agent conflicts. Use `--no-agents` to skip agent registration.

Add a credential from your terminal without placing the value in chat or a process argument:

```bash
printf '%s' "$MY_API_TOKEN" | s-gw secret add-keychain \
  --name demo-token \
  --type api-token \
  --value-stdin \
  --inject-env API_TOKEN \
  --allow-command "$(command -v printenv)"
```

Then inspect the non-secret handle metadata:

```bash
s-gw secret list
```

The [end-to-end trust loop](docs/quickstart.md) walks through a disposable request, local approval, execution, and output sanitization without touching a real credential.

## Try The Trust Loop

Use a disposable local token to see the full flow:

```bash
printf '%s' 'demo-secret-value' | s-gw secret add-keychain \
  --name demo-printenv-token \
  --type api-token \
  --value-stdin \
  --inject-env DEMO_TOKEN \
  --allow-command "$(command -v printenv)"

s-gw request env-command <returned-handle> \
  --command "$(command -v printenv)" \
  --inject-env DEMO_TOKEN

s-gw approve <request-id>
s-gw execute <request-id>
```

The execution output should show a handle token instead of `demo-secret-value`.

## Agent Integration

List the known agent profiles and render the configuration for one client:

```bash
s-gw agent list
s-gw agent mcp-snippet codex
s-gw agent mcp-snippet claude-code
s-gw agent mcp-snippet opencode
```

Review or manage detected connections:

```bash
s-gw agent status
s-gw agent install codex --dry-run
s-gw agent install codex
s-gw agent uninstall codex
```

Manual profiles and config formats without a safe merge path continue to use the generated snippet. npm installation itself never edits agent configuration.

`s-gw setup` can safely manage detected Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot CLI, OpenCode, and de