quick-shell

quick-shell is a local MCP App for short, human-approved SSH terminal sessions and confined SFTP file operations. An agent can request open_quick_shell for an SSH-configured device alias, but the user controls the terminal and file explorer.

Developer Setup

npm install
go test ./...
go vet ./...
npm run lint
npm run format:check
npm run typecheck
npm test
npm run test:coverage
npm run build
npm run smoke:stdio
npm run check

Useful development commands:

npm run dev              # rebuild the MCP app and run the HTTP server with a dev token
npm run serve:stdio      # run the built stdio MCP server
npm run serve            # run the built localhost HTTP MCP server
npm run verify:deployment
npm run test:sftp-integration -- dist/bin/quick-shell-sftp /path/to/ssh_config host-alias

Stdio is the recommended production transport:

npm run build
node dist/server/server/main.js --stdio

HTTP mode is localhost-only and requires bearer auth:

QUICK_SHELL_HTTP_TOKEN='replace-me' node dist/server/server/main.js --http

Requests to /mcp must include Authorization: Bearer <token>. The HTTP MCP server binds to 127.0.0.1 and does not enable broad CORS.

Related MCP server: ssh-mcp-server

Local CLI

The local CLI opens a human-controlled SSH terminal directly:

npm run build
node dist/server/cli/main.js --list
node dist/server/cli/main.js test-device --suggest 'hostname'

--list prints explicit SSH aliases plus optional metadata columns: alias, label, group, and danger.

--suggest keeps the suggested command outside the SSH PTY until the user presses Ctrl-G. That explicit action inserts the command without pressing Enter, so the user can edit or delete it before running it. No timer writes suggestion bytes into host-key, password, or other SSH prompts.

The local CLI does not accept --reason. Use the MCP API reason field when the caller needs to explain why a session is being requested.

Configuration

File explorer limits use QUICK_SHELL_MAX_FILE_ENTRIES=1000, QUICK_SHELL_MAX_FILE_METADATA_BYTES=524288, QUICK_SHELL_MAX_FILE_PATH_BYTES=4096, QUICK_SHELL_MAX_FILE_COMPONENT_BYTES=255, QUICK_SHELL_MAX_FILE_PATH_DEPTH=64, QUICK_SHELL_MAX_FILE_QUEUED_OPERATIONS=8, QUICK_SHELL_MAX_TRANSFER_BYTES=536870912, QUICK_SHELL_MAX_EMBEDDED_DOWNLOAD_BYTES=8388608, QUICK_SHELL_FILE_OPERATION_LEASE_TTL_MS=60000, QUICK_SHELL_MAX_FILE_OPERATION_LEASES=16, QUICK_SHELL_FILE_METADATA_TIMEOUT_MS=30000, QUICK_SHELL_FILE_TRANSFER_MAX_DURATION_MS=1800000, and QUICK_SHELL_FILE_SHUTDOWN_TIMEOUT_MS=5000. QUICK_SHELL_SFTP_HELPER may override the bundled dist/bin/quick-shell-sftp path.

Devices

V1 accepts only explicit Host aliases from the configured SSH config. Parsed membership is authoritative for names, so safe aliases such as home/lab are accepted; aliases beginning with - or containing whitespace/control characters are rejected as unsafe SSH arguments. Wildcards such as Host *, prod-*, and negated aliases are ignored. Escaped Host patterns are rejected conservatively so a partial token cannot become an alias.

Only globally reachable Include directives are followed recursively, including simple * and ? path globs. Includes inside Host or Match blocks do not contribute aliases. Relative include paths are resolved the same way OpenSSH resolves user config includes: under $HOME/.ssh. The primary SSH config must be readable; optional included files that do not exist are skipped. Include entries that require OpenSSH token expansion, environment expansion, or another user's ~user home expansion are rejected because quick-shell cannot safely validate the same file OpenSSH would load.

The parser rejects SSH config that can execute local commands before the user reaches the remote shell:

• ProxyCommand values other than none

• KnownHostsCommand values other than none

• LocalCommand

• RemoteCommand values other than none

• PermitLocalCommand enabled (yes, true, or 1)

• PKCS11Provider values other than none

• SecurityKeyProvider values other than internal

These directives are rejected wherever they appear, including inside files pulled in by an Include under a Host or Match block.

• Match exec and negated forms such as Match !exec

Add a device to the SSH config:

Host test-device
  HostName 192.0.2.10
  User operator

Then ask the agent to open quick-shell for test-device.

Optional quick-shell.toml metadata can decorate SSH aliases without granting access:

[devices.test-device]
label = "Test Device"
group = "dev"
danger = "normal"
default_shell = "zsh"

Metadata supports only [devices.<alias>] tables with quoted string values for label, group, danger, and default_shell. danger must be normal, caution, or danger. Metadata for aliases that are not in the SSH allowlist is ignored by session creation.

Secure Remote Bridge

The bridge is localhost-only by default. For remote MCP App hosts, expose /terminal, /files/upload, and /files/download through a TLS reverse proxy and advertise that public base URL:

QUICK_SHELL_BRIDGE_HOST=0.0.0.0 \
QUICK_SHELL_BRIDGE_PORT=40101 \
QUICK_SHELL_BRIDGE_PUBLIC_URL=https://shell.example.com \
QUICK_SHELL_ALLOWED_ORIGINS=https://mcp-host.example.com \
node dist/server/server/main.js --stdio

Remote bridge requirements:

• Proxy only the bridge paths needed by the app: /terminal, /files/upload, and /files/download.

• Set QUICK_SHELL_BRIDGE_PUBLIC_URL to an origin with no path prefix; v1 serves /terminal, /files/upload, and /files/download at that origin's root.

• Preserve WebSocket upgrade headers.

• Disable proxy buffering on file routes and enforce compatible body and timeout limits.

• Use HTTPS for QUICK_SHELL_BRIDGE_PUBLIC_URL; the app receives a wss:// terminal URL.

• Set QUICK_SHELL_ALLOWED_ORIGINS to the MCP App host origin or a comma-separated list. When the list is non-empty, requests without a matching Origin are rejected before WebSocket upgrade. Hosts that sandbox app iframes on rotating per-connector origins (Claude uses {hash}.claudemcpcontent.com) need a wildcard entry such as https://*.claudemcpcontent.com; wildcards match exactly one subdomain label, and the per-session WebSocket token remains the actual authentication.

• Keep QUICK_SHELL_ALLOWED_ORIGINS empty only for local-only deployments. It is required whenever QUICK_SHELL_BRIDGE_PUBLIC_URL is set: the server refuses to start on that combination, even if a proxy in front of it already enforces origins.

• Keep tool-result _meta hidden from the model. App tokens and WebSocket tokens are capabilities and must remain app-only.

The WebSocket URL contains only the session id. The app authenticates with a per-session WebSocket token in its first bridge message.

API and Capability Model

quick-shell follows the MCP Apps standard first. open_quick_shell declares _meta.ui.resourceUri, the app resource is served as text/html;profile=mcp-app, and the iframe talks to the host through the standard ui/* bridge. ChatGPT/OpenAI compatibility aliases are also present, including openai/outputTemplate, widget visibility, and status metadata. App-only sibling tools are private, token-gated callbacks; they do not bind their own app resource or output template.

App resource:

Tools:

SFTP Safety Model

The Files view starts its helper lazily and uses system OpenSSH with the same configured alias, keys, agent, host verification, and ProxyJump behavior as the terminal. Authentication is noninteractive (BatchMode=yes), so accept a new host key or unlock a key through the terminal first when necessary.

Paths are relative to the remote account's canonical home. The server bounds path bytes, component bytes, depth, directory entries, pending operations, transfer bytes, and lease lifetime. This is a user-safety boundary, not race-proof isolation from a malicious process running as the same remote user. Symlinks are listed distinctly and destructive operations require explicit UI confirmation plus a fresh one-use lease.

Transfers use fixed bridge routes with a separate file bearer in request headers. Capabilities, leases, and paths do not appear in URLs or model-visible MCP content. Downloads are bounded and appear only when the host advertises downloadFile; larger or resumable transfers remain out of scope.

open_quick_shell returns model-visible text plus structured public session fields: sessionId, device, optional reason, optional suggestedCommand, and optional device metadata. The model-visible text says the session is prepared, not opened: the SSH PTY starts only after a compatible MCP App host renders the app and attaches through the bridge or app-only fallback. Hidden _meta.quickShell contains the app token. Hidden _meta.quickShellSession may also include bridge URL, WebSocket token, limits, and ping cadence so the app can attach immediately.

App-only tools require the hidden app token. Direct WebSocket sessions require the hidden WebSocket token. Tokens are never placed in model-visible content or structuredContent.

Architecture and Session Topology

One runtime process owns:

• MCP server registration and transports.

• The terminal bridge HTTP/WebSocket listener.

• The in-memory session manager.

• SSH PTYs and bounded scrollback buffers.

• Cleanup timers and audit logging.

open_quick_shell creates a session and tokens, but the SSH PTY starts only when the MCP App attaches through the bridge or app-only fallback. Each session has one active bridge socket; a newer view replaces the previous socket. App-only fallback uses the same session manager and token model, so it must reach the same runtime process that created the session.

Deployment topology matters. If you run multiple quick-shell replicas, route each session's MCP app-only tools and /terminal bridge traffic back to the same process that handled open_quick_shell, or use a single upstream instance. Round-robin routing without sticky affinity will produce invalid or missing session capability errors.

Important sticky limits:

• Default maximum live sessions per process is 4.

• Sessions expire by absolute age and idle timeout.

• Sessions are closed on process shutdown and process signals.

• Bridge clients are closed on authentication timeout, invalid schema, invalid token, backpressure, or session replacement.

• There is no durable transcript or session resume in v1.

Output Handling

Terminal output is bounded in memory. When the user clicks Send output, the app normalizes recent output, strips terminal control sequences, truncates to the configured byte limit, and shows an editable confirmation dialog. The app warns about five specific secret-looking patterns: OpenAI-style sk- keys, OpenSSH private key headers, password = assignments, token = assignments, and Authorization: Bearer headers.

This is not a DLP system. The warning pass is a best-effort prompt for human review, not a guarantee that secrets or sensitive data are detected. The user remains responsible for editing or canceling output before confirming.

Output return uses app.sendMessage. A compatible host must render the app, connect the terminal bridge or app-only fallback, and accept app.sendMessage so the approved output appears in the conversation. If app.sendMessage is unsupported or rejected, the app keeps the send dialog open and shows a copyable fallback. That host is unsupported for full v1 output return.

Download, when offered by the host, exports sanitized recent scrollback through ui/download-file. ui/update-model-context is used only for session state, never for terminal output.

Audit breadcrumbs can include session ids, device aliases, whether a reason was present, suggested command text, byte counts, bridge rejection reasons, startup errors, and lifecycle events. They do not include terminal output or app/WebSocket tokens.

Host Compatibility and Accessibility

The UI adopts host context when available:

• host theme, style variables, fonts, safe-area insets, and display mode

• ui/request-display-mode for inline/fullscreen switching when offered

• ui/download-file for user-initiated output export when offered

• ui/update-model-context for session state only

• host logging for app errors when offered

Host-specific controls stay hidden when their host capability is unavailable. The app uses host-neutral visible copy and exposes labels/live regions for the session status, suggested command field, terminal region, and send-output dialog.

Deployment Verification

A deployment can be checked with:

npm run verify:deployment

The verifier contract is intentionally stricter than a process liveness check. It verifies:

• local build manifest exists, is clean, and matches local HEAD

• deployed source path and build manifest exist

• deployed manifest fields and file hashes match the local build

• optional gateway config env expectations are present

• gateway upstream command and args match the expected process

• gateway runtime is connected and exposes the expected tool count

• app-only tools remain app-visible, OpenAI-private, and free of app resource/output-template bindings

• check_quick_shell can be called through the gateway

• resource smoke: the deployed server serves the app resource as text/html;profile=mcp-app and exposes every runtime tool

• audit log smoke: when QUICK_SHELL_VERIFY_AUDIT_LOG is set, the log contains runtime_started and bridge_listening with the expected baseUrl

Verifier environment:

On failure, the verifier returns failures plus a recovery hint: restart or recycle the configured gateway upstream, then rerun with the same QUICK_SHELL_VERIFY_* environment.

Operations, Rollback, and Incidents

Before deploying, run:

npm run check
npm run smoke:stdio

After deploying, run npm run verify:deployment and at least one manual app smoke scenario from docs/manual-app-smoke.md.

Operational checks:

• Confirm check_quick_shell succeeds through the gateway.

• Confirm the gateway reports the upstream as connected with the expected exposed tool count.

• Confirm app-only tools remain private, token-gated callbacks without their own app resource/output-template binding.

• Confirm the bridge public URL and allowed origins match the host that will render the app.

• Review the audit log for startup failures, bridge rejections, stale sessions, and cleanup events.

Rollback:

1. Restore the previous built quick-shell source or package at the deployment path.

2. Restore the previous gateway command, args, and quick-shell environment.

3. Restart or recycle the gateway upstream so the stdio process and bridge listener are replaced.

4. Rerun npm run verify:deployment.

5. Run the manual smoke scenario that previously failed.

Incident response:

1. Disable or stop the quick-shell upstream to kill active sessions and invalidate in-memory app/WebSocket tokens.

2. Remove or disable the public /terminal reverse-proxy route if bridge exposure is suspected.

3. Preserve audit logs before restarting if investigation is needed.

4. Rotate QUICK_SHELL_HTTP_TOKEN for HTTP mode and any external gateway secret that can launch the server.

5. Restart with known-good config, verify deployment, and run manual smoke before re-enabling access.

Manual Smoke

See docs/manual-app-smoke.md for the scenario matrix covering baseline app attach, prefill behavior, app-only fallback, host capability gating, output return, unsupported hosts, and remote bridge origin checks.

V1 Deferrals

• Target daemons

• Non-SSH transports

• Remote or multi-user auth

• Windows PTY guarantees

• Durable transcripts or session resume

License

Copyright 2026 Jacob Magar.

PolyForm Noncommercial 1.0.0 — free for personal, hobby, research, and educational use. Any commercial use requires a separate license; open an issue to enquire.

This is a source-available license, not an OSI-approved open source license.