{"id":50222342,"url":"https://github.com/matthiastjong/shellgate","last_synced_at":"2026-06-03T16:00:47.535Z","repository":{"id":347593750,"uuid":"1183477007","full_name":"matthiastjong/shellgate","owner":"matthiastjong","description":"Self hosted secure gateway for AI agents. One token. Full control. Complete audit trail.","archived":false,"fork":false,"pushed_at":"2026-05-26T12:47:15.000Z","size":834,"stargazers_count":15,"open_issues_count":1,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T14:32:53.725Z","etag":null,"topics":["ai","ai-agents","api-gateway","claude-code","credential-management","mcp","mcp-server","model-context-protocol","open-source","proxy","security","self-hosted","ssh","ssh-proxy"],"latest_commit_sha":null,"homepage":"https://shellgate.ai","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matthiastjong.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-16T16:40:14.000Z","updated_at":"2026-05-26T12:47:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/matthiastjong/shellgate","commit_stats":null,"previous_names":["matthiastjong/shellgate"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/matthiastjong/shellgate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthiastjong%2Fshellgate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthiastjong%2Fshellgate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthiastjong%2Fshellgate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthiastjong%2Fshellgate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matthiastjong","download_url":"https://codeload.github.com/matthiastjong/shellgate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthiastjong%2Fshellgate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33872298,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","api-gateway","claude-code","credential-management","mcp","mcp-server","model-context-protocol","open-source","proxy","security","self-hosted","ssh","ssh-proxy"],"created_at":"2026-05-26T13:00:18.257Z","updated_at":"2026-06-03T16:00:47.520Z","avatar_url":"https://github.com/matthiastjong.png","language":"TypeScript","funding_links":[],"categories":["Cloud Infrastructure","📦 Other"],"sub_categories":["🔒 Security"],"readme":"# Shellgate\n\n[![GitHub Stars](https://img.shields.io/github/stars/matthiastjong/shellgate?style=flat)](https://github.com/matthiastjong/shellgate/stargazers)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Docker](https://img.shields.io/badge/docker-ready-blue)](https://ghcr.io/matthiastjong/shellgate)\n[![TypeScript](https://img.shields.io/badge/TypeScript-blue?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-green)](https://modelcontextprotocol.io/)\n\n**Stop giving your AI agents your API keys.**\n\nShellgate sits between your AI agents and your infrastructure. Agents get a scoped token — they never see real credentials, SSH keys, or passwords. You control what runs, everything is logged, and dangerous commands ask for your approval before executing.\n\n```\nAgent → sg_token → Shellgate → Your APIs / SSH Servers / Tools\n                       │\n                       ├─ credentials injected (agent never sees them)\n                       ├─ dangerous commands intercepted → approval required\n                       └─ every request logged\n```\n\n## Why Shellgate?\n\n**Without Shellgate:**\n- Agents hold your real API keys and SSH credentials\n- Revoking access means rotating keys everywhere\n- No visibility into what your agents are doing\n- One prompt injection = your production server is compromised\n\n**With Shellgate:**\n- Agents only hold scoped, revocable `sg_` tokens\n- Revoke one token without affecting anything else\n- Every request is logged and auditable\n- Dangerous commands are intercepted before they execute\n\n---\n\n\u003e **🔒 Security note:** Run Shellgate on a separate machine from your AI agent. Agents like OpenClaw have access to the host filesystem. If Shellgate runs on the same machine, the agent could access the database directly, bypassing all access controls. A cheap VPS (Hetzner, Railway, etc.) is all you need, or use [Shellgate Cloud](https://shellgate.cloud) for a fully managed setup.\n\n---\n\n## Shellgate Cloud\n\nShellgate Cloud gives you a secure agent gateway in under a minute -- no Docker, no setup.\n\n**[Shellgate Cloud](https://app.shellgate.cloud)** is the managed version. Sign up, get a dedicated instance, and connect your agent immediately.\n\n- Fully managed -- no Docker, no servers\n- Ready in under a minute\n- Daily backups included\n- 14-day free trial, no credit card needed\n\n[**Try Shellgate Cloud for free**](https://app.shellgate.cloud)\n\nPrefer full control? Keep reading to self-host.\n\n---\n\n## Quick Start\n\n### 1. Run Shellgate\n\n**Docker image:**\n\n```bash\ndocker run -d \\\n  -p 3000:3000 \\\n  -e DATABASE_URL=postgres://user:pass@host:5432/shellgate \\\n  -e SESSION_SECRET=$(openssl rand -hex 32) \\\n  ghcr.io/matthiastjong/shellgate:latest\n```\n\nThis assumes you already have a PostgreSQL database running. Point `DATABASE_URL` at your existing instance.\n\n**Docker Compose:**\n\n```yaml\nservices:\n  shellgate:\n    image: ghcr.io/matthiastjong/shellgate:latest\n    ports:\n      - \"3000:3000\"\n    environment:\n      DATABASE_URL: postgres://postgres:postgres@db:5432/shellgate\n      SESSION_SECRET: change-me-to-a-random-string\n    depends_on:\n      - db\n\n  db:\n    image: postgres:16-alpine\n    environment:\n      POSTGRES_DB: shellgate\n      POSTGRES_PASSWORD: postgres\n    volumes:\n      - pgdata:/var/lib/postgresql/data\n\nvolumes:\n  pgdata:\n```\n\n```bash\ndocker compose up -d\n```\n\n### 2. Set Up Your Account\n\nOpen `http://localhost:3000` → create your admin account on the setup screen.\n\n### 3. Add a Target\n\nA **target** is any upstream API you want agents to access (OpenAI, Anthropic, Stripe, your internal services, etc.).\n\nGo to **Targets** → **Add Target**:\n- **Name:** `openai`\n- **Base URL:** `https://api.openai.com`\n- **Auth:** Add your OpenAI API key as a Bearer token\n\n### 4. Create an API Key\n\nGo to **API Keys** → **Create Key**:\n- Give it a name (e.g. `my-agent`)\n- Grant it permission to the `openai` target\n- Copy the `sg_...` token\n\n### 5. Use It\n\nYour agent now talks to Shellgate instead of OpenAI directly:\n\n```bash\n# Before: agent has your real API key\ncurl https://api.openai.com/v1/chat/completions \\\n  -H \"Authorization: Bearer sk-your-real-key\" \\\n  -d '{\"model\":\"gpt-4o\",\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}]}'\n\n# After: agent only has a Shellgate token\ncurl http://localhost:3000/gateway/openai/v1/chat/completions \\\n  -H \"Authorization: Bearer sg_your-shellgate-token\" \\\n  -d '{\"model\":\"gpt-4o\",\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}]}'\n```\n\nSame request, same response. But now you control access, can revoke tokens instantly, and have a full audit trail.\n\n**SSH targets** work the same way — add a server as a target, give your agent a token, and it can run commands without ever seeing your SSH key:\n\n```bash\ncurl -X POST http://localhost:3000/ssh/prod-server/exec \\\n  -H \"Authorization: Bearer sg_your-shellgate-token\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"command\": \"docker ps\", \"timeout\": 30}'\n```\n\nIf the command is flagged as dangerous (e.g. `rm -rf`, `systemctl stop`), Shellgate returns a `202 approval_required` response instead of executing — your agent asks you first.\n\n---\n\n## Deploy\n\nShellgate runs anywhere Docker runs. You can run it on your laptop for development, but for production we recommend a remote server so your agents have a stable endpoint.\n\n| Platform | How |\n|---|---|\n| **Any VPS** (Hetzner, DigitalOcean, etc.) | `docker compose up -d` |\n| **Railway** | Deploy from GitHub, set env vars |\n| **Render** | Docker deploy, set env vars |\n| **Coolify / Dokploy** | Add from Git repo, auto-detected |\n| **Fly.io** | `fly launch`, attach Postgres |\n\n**Requirements:**\n- PostgreSQL 14+\n- Node.js 22+ (if running without Docker)\n\n**Environment variables:**\n\n| Variable | Required | Description |\n|---|---|---|\n| `DATABASE_URL` | ✅ | PostgreSQL connection string |\n| `SESSION_SECRET` | ✅ | Random string for session encryption |\n\n---\n\n## Features\n\n### Gateway Proxy\nRoute agent requests to any upstream API. Shellgate injects the real credentials so agents never see them.\n\n### Token Management\nCreate, revoke, and rotate `sg_` tokens from the dashboard. Each token can be scoped to specific targets.\n\n### Per-Token Permissions\nControl exactly which APIs each agent can access. Agent A gets OpenAI, Agent B gets Anthropic. You decide.\n\n### Dashboard\nWeb UI for managing targets, tokens, and permissions. No CLI required.\n\n### Agent Integration\nBuilt-in install scripts for **Claude Code**, **OpenClaw**, and **Hermes**. Connect your agent in one click from the dashboard.\n\n### SSH Execution\nRun commands on remote servers through Shellgate. Same token, same audit trail.\n\n### Human-in-the-Loop Guard\nShellgate intercepts dangerous commands before they execute and asks for your approval. Built-in protection out of the box — no configuration needed.\n\n**How it works:**\n1. Agent sends a command (e.g. `rm -rf /var/backups/2024`)\n2. Shellgate matches it against the built-in ruleset\n3. Instead of executing, it returns `approval_required`\n4. Your agent surfaces this to you — you approve or deny\n5. Agent re-sends with `X-Shellgate-Approved: true` → executes\n\n```json\n{\n  \"status\": \"approval_required\",\n  \"reason\": \"Command contains 'rm -r'\",\n  \"matched\": \"rm -r\",\n  \"request\": { \"type\": \"ssh\", \"command\": \"rm -rf /var/backups/2024\" }\n}\n```\n\nWorks for both SSH commands and API calls (e.g. `DELETE` requests). Destructive patterns like `rm -r`, `DROP TABLE`, `systemctl stop`, and `DELETE FROM` trigger approval by default. Blocked patterns like `/etc/shadow` and `curl | bash` are always rejected, regardless of approval.\n\nThis also acts as a **prompt injection defense** — even if a malicious prompt tricks your agent into sending a dangerous command, Shellgate catches it before it reaches your infrastructure.\n\n### MCP Server\n\nShellgate exposes all agent-facing functionality as an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server. Claude Code and other MCP-compatible agents connect directly — no REST calls needed.\n\n**Built-in tools:**\n\n| Tool | Description |\n|---|---|\n| `discover` | List accessible targets, webhooks, and org skills |\n| `api_request` | Proxy HTTP requests with automatic credential injection |\n| `api_download` | Download authenticated image responses as temporary MCP resources with content-type and size checks |\n| `ssh_exec` | Execute SSH commands with guard protection |\n| `webhook_poll` | Poll for incoming webhook events |\n| `webhook_ack` | Acknowledge processed webhook events |\n| `vault_search` | Search credential vault for blind-fill handles |\n| `memory_list` / `memory_read` / `memory_add` / `memory_delete` | Manage agent memories |\n| `org_skill_list` / `org_skill_read` / `org_skill_upsert` / `org_skill_delete` | Manage shared organization skills |\n| `wiki_list_pages` / `wiki_read_page` / `wiki_upsert_page` / `wiki_delete_page` / `wiki_lint_page` | Organization knowledge base |\n\nConnect via `mcpServers` config pointing to `POST /mcp` with your `sg_` token as the Bearer header.\n\n### Webhooks\n\nReceive webhooks from external services (Stripe, GitHub, Slack, etc.) and route them to your agents.\n\n1. Create a webhook endpoint in the dashboard — you get a unique URL\n2. Point external services at that URL\n3. Your agent polls for new events and acknowledges them when processed\n\nEach endpoint supports optional **handling instructions** — plain text guidance that tells the agent what to do when an event arrives.\n\n### Vault\n\nStore and manage credentials securely. Agents never see raw secrets — they get blind-fill handles that Shellgate resolves at request time.\n\n- Organize credentials into multiple vaults\n- Per-token vault permissions\n- Sensitive fields are encrypted and never exposed to agents\n- `vault_search` MCP tool lets agents discover available credentials by domain\n\n### Organization Skills\n\nShared, reusable procedures that any agent can access. Skills are markdown documents with structured instructions — like runbooks your agents can follow.\n\n- Create and version skills from the dashboard or via MCP\n- Agents call `org_skill_list` to discover available skills\n- Call `org_skill_read` to load a skill's full instructions before executing\n\n### Memories\n\nGive your agents persistent memory across sessions. Memories can be scoped to the organization, a specific user, or a specific token.\n\n- Agents store and recall context between conversations\n- Three visibility levels: `org`, `user`, `token`\n- Full CRUD via MCP tools\n\n### Wiki\n\nA built-in knowledge base for compiled organizational knowledge. Store research, documentation, and reference material that agents can query.\n\n- Multi-namespace support\n- Status tracking (draft, active, archived)\n- Source attribution\n- Tagging and search\n- Built-in linting/validation\n\n### Audit Log\n\nEvery gateway request, SSH command, and guard action is logged with full context — method, path, status code, duration, client IP, and guard decisions. Searchable from the dashboard.\n\n---\n\n## Run from Source\n\n```bash\ngit clone https://github.com/matthiastjong/shellgate.git\ncd shellgate\nnpm install\ncp .env.example .env  # edit DATABASE_URL and SESSION_SECRET\nnpm run dev\n```\n\nOpen `http://localhost:5173`.\n\n---\n\n## API Reference\n\nAll management endpoints require admin authentication (session cookie from dashboard login).\n\nAgent endpoints use Bearer token authentication (`sg_` tokens).\n\n### Gateway\n\n```\nANY /gateway/:target/*\n```\nProxies the request to the target's base URL with injected auth. Requires a valid `sg_` Bearer token with permission for the target.\n\n### Tokens\n\n```\nPOST   /api/tokens              # Create token\nGET    /api/tokens              # List tokens\nDELETE /api/tokens/:id          # Revoke token\nPOST   /api/tokens/:id/regenerate  # Regenerate token\n```\n\n### Targets\n\n```\nPOST   /api/targets             # Create target\nGET    /api/targets             # List targets\nPATCH  /api/targets/:id         # Update target\nDELETE /api/targets/:id         # Delete target\n```\n\n### Permissions\n\n```\nPOST   /api/tokens/:id/permissions          # Grant target access\nDELETE /api/tokens/:id/permissions/:targetId # Revoke target access\n```\n\n### SSH\n\n```\nPOST /ssh/:target/exec   # Execute a command on an SSH target\n```\n\nBody: `{ \"command\": \"string\", \"timeout\": 30 }` (timeout optional, max 60s)\n\nResponse: `{ \"exitCode\": 0, \"stdout\": \"...\", \"stderr\": \"...\", \"durationMs\": 123 }`\n\nIf the command is intercepted by the guard: `{ \"status\": \"approval_required\", \"reason\": \"...\", \"matched\": \"...\", \"request\": {...} }` (HTTP 202)\n\nRe-submit with `X-Shellgate-Approved: true` header to execute after human approval.\n\n### MCP\n\n```\nPOST /mcp   # MCP server (Streamable HTTP transport)\n```\n\nBearer token auth. All tools listed in [MCP Server](#mcp-server) are available.\n\n### Webhooks\n\n```\nPOST /webhooks/incoming/:slug         # Receive webhook from external service\nGET  /webhooks/poll                   # Poll pending events (Bearer token)\nPOST /webhooks/ack                    # Acknowledge events (Bearer token)\n```\n\n### Discovery\n\n```\nGET /discovery   # List targets, webhooks, and skills accessible to this token\n```\n\n### Health\n\n```\nGET /health   # Returns { status: \"ok\" }\n```\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatthiastjong%2Fshellgate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatthiastjong%2Fshellgate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatthiastjong%2Fshellgate/lists"}