s-gw

Local credential control for coding agents.
Approve bounded actions locally. Keep raw credentials out of model context and tool output.

Demo · Downloads · Quick start · Documentation · Security · Contributing

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.

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. 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.

Public demo: s-gw.com.

What It Does

Why Teams Use It

• Local custody: raw values stay in macOS Keychain, Linux Secret Service, 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: native desktop apps, tray or menu helpers, the CLI, and the web console show approvals, credential inventory, policies, usage flow, activity, and audit history.

How It Works

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

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:

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: the npm package uses the TypeScript execution path and includes the PowerShell client, tray helper, and local web console.

On Linux, install secret-tool first (sudo apt install libsecret-tools on Ubuntu/Debian). An unlocked desktop Secret Service is the normal persistent unlock provider; s-gw setup also installs and starts an owner-level systemd --user console service for the graphical session. A headless host without Secret Service can use an explicitly supplied SGW_MASTER_PASSPHRASE with s-gw setup --no-service --no-open-app, but s-gw never copies that value into a unit file or background-service environment.

Windows x64 and Linux x64 also have installable desktop-app builds. The Rust app draws its management interface directly in a native window; it does not embed a browser, WebView, or localhost page. It packages its own pinned Node runtime and s-gw CLI, so the installed app does not require host Node.js or npm. When the native executable is installed, s-gw app open uses it. Use s-gw app open --browser to start and open the separate loopback browser backup explicitly.

These Windows NSIS and Linux Debian packages are currently unsigned CI previews, not supported public release downloads. Windows does not require WebView2. Linux requires a graphical session and an unlocked Secret Service keyring; the Debian package declares its GTK 3, AppIndicator, libxdo, and libsecret-tools runtime dependencies. See deployment and packaging for build and install details.

For an Apple Silicon Mac desktop bundle, GitHub 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 and the native-rendered Windows/Linux Rust desktop app. Building the native macOS surfaces also requires a Swift toolchain. Windows and Linux desktop builds require Rust and their ordinary native graphics and tray development libraries. 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.

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 and the Windows/Linux desktop previews run their bundled runtimes in place; npm installs copy the thin macOS 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:

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:

s-gw secret list

The end-to-end trust loop 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:

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:

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:

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 default-profile VS Code installations on macOS, Windows, and Linux. On Windows, it launches the packaged MCP server through node.exe, not an npm .cmd shim.

For CLI agents, guard mode can replace credential-looking launch environment values with s-gw handles before the agent starts:

s-gw run codex --dry-run -- -v
s-gw run codex -- --ask-for-approval never

MCP registration does not intercept every prompt, file read, shell, or environment variable. See agent integration and the agent profile matrix for the supported paths and current limitations.

Example Request Flow

1. An agent sees s-gw:credential:prod-readonly and asks to run aws sts get-caller-identity.
2. s-gw creates a pending request with the agent name, command, handle, environment binding, working directory, target, and policy result.
3. You approve once, for a time window, for the login session, or deny it.
4. s-gw starts the approved local process with the credential injected into the requested environment variable.
5. s-gw scans the process output before it returns to the agent.

The model can complete the task without receiving the raw access key.

Platform Status

Published Apple Silicon macOS DMGs are self-contained. Releases are Developer ID signed and notarized when credentials are available; otherwise the release notes and DMG README state that a Gatekeeper override is required. Windows NSIS and Linux Debian desktop packages are currently unsigned CI artifacts and are not uploaded as supported release downloads. Build either one on its target operating system with npm run build:desktop-app; build the existing release artifacts with npm run build:installers.

Security Model

s-gw is designed to reduce accidental credential exposure to coding agents. It does not protect against a compromised operating system account, a malicious approved executable, screen capture, kernel-level access, or every transformed derivative of a secret.

Read the threat model before relying on s-gw for sensitive workflows. Report suspected vulnerabilities through GitHub private vulnerability reporting, not a public issue.

Project Status

• The public broker and client source distribution is preview quality; the compiled Rust execution core is proprietary.
• macOS is the primary development and test platform.
• Windows Credential Manager support and the Windows x64 desktop app are present but still need broader native QA and code signing.
• Linux uses Secret Service for persistent unlock material and a hardened systemd user service. The Linux x64 desktop app is an unsigned preview; environment unlock is a non-persistent headless fallback only.
• Windows and Linux desktop installers are CI previews until they are signed and validated on supported target systems. macOS releases without Developer ID signing are marked unsigned in their release notes and require a Gatekeeper override.
• The repository is prepared for open-source collaboration, but security-sensitive changes should come with focused tests and threat-model updates when behavior changes.

Documentation

• Documentation index
• Quick start and trust-loop demo
• Architecture
• Threat model
• Agent integrations
• Credential stores and 1Password
• Deployment and packaging
• Third-party assets and licenses

Contributing

Issues and focused pull requests are welcome. Start with CONTRIBUTING.md, browse good first issue, and use SECURITY.md for anything that may expose credentials or bypass approval.

Planning a launch, write-up, or community post? The maintainer notes in docs/community-launch.md keep the public wording consistent and honest.

License

Source in this repository is Apache-2.0. See LICENSE and NOTICE. The separately maintained Rust core and its compiled binaries are proprietary and are not licensed under Apache-2.0. Third-party names and artwork remain the property of their respective owners and are documented in TRADEMARKS.md and the third-party notices.