Gateway SSH

View saved version →

---
name: discovery-and-recovery
description: "Gateway discovery and recovery. Current typed discovery, host-probe, reboot, update, and bounded shell fallback discipline."
---

<!-- Generated by scripts/build-openai-plugin.ts from workers/api/src/mcp/guidance.ts. Do not edit by hand. -->

# Gateway discovery and recovery

## Current capability map

### SSH provisioning recovery

- Available: get_server_auth_status returns only the authenticated account's password-attempt state and Gateway-key verification history for one owned server.
- When password authentication is permanently disabled, do not retry it. Have the user install the server's Gateway public key through a trusted console or existing access path, then call verify_ssh_key.
- Target-wide pressure, other customers' activity, risk scores, and internal thresholds are deliberately unavailable.

### Filesystem discovery and reads

- Available: stat_file and hash_file for exact paths; list_directory and find_files for bounded discovery without following links; search_file_contents for bounded UTF-8 literal or regex search; and read_file with bounded offset or stable cursor paging.
- Keep roots, depth, result count, per-file bytes, and total bytes explicit. A read cursor is bound to file identity, size, and modification time and fails closed if the file changes.
- Opt-in proactive detection: read get_file_scanning_preferences, then use scan_server_file only when allow_server_file_scanning=true. Gateway enforces that preference and routes an expected-hash regular file through its internal asynchronous transfer scanner; destructive response remains a separate authority.

### Docker introspection

- Available: list_docker_containers, inspect_docker_image, inspect_docker_container, get_docker_container_stats, exact container start/stop/restart and bounded logs, plus the advertised Compose tools.
- exec_docker_container accepts a bounded argv vector for one exact running container. copy_from_docker_container and copy_to_docker_container copy one exact regular file and refuse an existing destination; overwrite cannot be enabled.

### systemd discovery

- Available: list_systemd_units, list_failed_systemd_units, and list_systemd_unit_files for bounded discovery; get_systemd_status, get_systemd_logs, get_systemd_dependencies, and allowlisted get_systemd_properties for exact units; plus daemon-reload and exact start/stop/restart/reload/try-reload/enable/disable/mask/unmask/reset-failed/kill tools. try_reload_systemd_unit never restarts an inactive or non-reloadable unit.

### Host-originated probes

- Available from the registered host: probe_tcp_from_host, request_http_from_host, inspect_tls_from_host, ping_from_host, and tracepath_from_host. Each accepts one exact destination and fixed bounds; HTTP does not follow redirects and TLS uses the host trust store.
- is_up, wait_until_up, and wait_until_down remain executor-originated checks of the registered server endpoint. Keep the probe origin explicit when interpreting evidence.

### Guarded reboot and update recovery

- Available: get_update_status, refresh_package_updates, exact package operations, update_system_packages, get_reboot_required, get_services_restart_required, and reboot_system_guarded.
- update_system_packages refuses package removals and never reboots. reboot_system_guarded observes SSH down/up, reconnects through pinned SSH trust and the leased identity, verifies a changed boot ID, and runs fixed post-boot health checks. Follow both as durable jobs to a terminal result.

### Firewalls and connection addresses

- A connection that times out or is refused before SSH negotiation starts often means a firewall, security group, or allowlist in front of the server is dropping or rejecting Gateway's connection.
- Such a failed job carries connectionFailure: connectFrom lists the addresses Gateway connected from for that server's region, and staticIp gives the account's static IP state there (active, pending, slot_availabl

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: operating-doctrine
description: "Gateway operating doctrine. Typed-tool selection, inspection-first operation, durable jobs, privilege and secret handoffs, and the execute_command escape hatch."
---

<!-- Generated by scripts/build-openai-plugin.ts from workers/api/src/mcp/guidance.ts. Do not edit by hand. -->

# Gateway operating doctrine

## Choose the safest expressive operation

1. Prefer a first-class typed Gateway tool when it cleanly expresses the requested operation.
2. Inspect and discover first, then use canonical server IDs, exact paths, exact units, exact containers, and explicit overwrite behavior.
3. Use dry-run and expected-state controls when the selected tool provides them.
4. Treat a returned job ID as durable work. Use get_job or wait_for_job until the required terminal state instead of assuming a short MCP wait completed the job.
5. Use execute_command for application-specific work, genuinely novel compositions, or a capability that Gateway does not yet model. It is an intentional escape hatch and must remain available.
6. If the same shell-composed workflow succeeds repeatedly, treat it as evidence for a future typed operation; do not imply that an unsupported typed tool already exists.

## Privilege

No tool accepts a sudo password. Privileged work uses privilege sudo or auto, or a typed tool that runs with sudo. When such a call fails with SUDO_PASSWORD_REQUIRED or SUDO_AUTH_FAILED, or a job carries nextAction request_sudo_access, call request_sudo_access for that server. If its state is action_required, ask the user how they would like to grant sudo (just this once, which covers a single privileged job; for a while, 15 minutes to an hour, which suits a task needing several privileged calls; or always: Gateway keeps the sudo password, or a passwordless sudo rule is installed on the server) and send them its setupUrl to choose and enter the password in Gateway. Never ask for a password in chat. Wait for the user to confirm, then retry the original call; the failure happens before the command runs, so retrying is safe. already_root needs no action; unsupported (Windows servers) means use privilege none. To set up a new server, send the user the add_server setupUrl to enter the login password in Gateway; sudo_setup chooses whether that password also grants sudo.

## Secrets

Gateway's job is to let the user use an agent without handing it secrets: secret values never pass through the conversation or tool arguments. When work needs a token, API key, registry credential, or secret file, call request_stored_value with a short name (for example github-token) and the purpose. If exists is false, send the user its setupUrl, wait for them to confirm the secret is saved, then pass only its name: stdin_from or env_from on execute_command and typed tools, registry_credential_from for registry access, and content_from on write_secret_file. A call that names a missing, used, or expired secret fails with nextAction request_stored_value before any job is created; follow the same handoff and retry. One-time secrets are consumed by the first job that uses them.

## File movement

Use copy_between_servers for one exact regular-file direct host-to-host copy up to 268,435,456,000 bytes (250 GiB). Recursive directory copy is not supported by v2. Gateway coordinates, authorizes, supervises, and audits the operation. Between directly reachable servers the payload flows only between the source and destination hosts; it never passes through an executor, the application server, artifact storage, or R2, and the copy fails when no direct host path is available rather than falling back to a relay. When either server connects through a Gateway overlay network, Gateway stages the file through regional R2 instead, capped at 5,363,466,240 bytes (4.995 GiB), and deletes it after the transfer. The operation uses short-lived transfer-scoped authorization. sync_between_servers retains staged/R2 transit by default and its existing ex

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: secure-transfer
description: "Gateway secure-transfer workflow. Staged/R2 transport doctrine and the enforced hash-reputation transfer workflow."
---

<!-- Generated by scripts/build-openai-plugin.ts from workers/api/src/mcp/guidance.ts. Do not edit by hand. -->

# Gateway secure-transfer workflow

## Transport choice

- copy_between_servers has no transport parameter and v2 accepts one regular file, not a recursive directory. Between directly reachable servers it coordinates a direct source-host-to-destination-host data path, defaults max_bytes to 268,435,456,000 (250 GiB), creates no artifact or R2 staging object, and never relays payload bytes through Gateway executors or the application server. When either server connects through a Gateway overlay network, it stages the file through regional R2 instead, capped at 5,363,466,240 bytes (4.995 GiB), and deletes it after the transfer. It uses short-lived transfer-scoped authorization and fails explicitly when neither host can directly reach the other.
- sync_between_servers defaults to transport=staged. Keep max_bytes at or below 5,363,466,240 (4.995 GiB) for staged Gateway/R2 sync.
- For sync_between_servers, transport=auto is capped at 5,363,466,240 bytes (4.995 GiB). It may attempt direct relay only when both endpoints share an authorized executor routing context and retains a staged fallback; it is not a way to request a larger sync.
- Explicit transport=direct for sync_between_servers supports max_bytes up to 268,435,456,000 bytes (250 GiB) only when both endpoints share that authorized routing context. When max_bytes exceeds 5,363,466,240 (the 4.995 GiB R2 single-part ceiling), transport=direct is required.
- Publicly obtainable artifact: have the destination fetch from the authoritative public source when practical.
- Host-to-host data above 268,435,456,000 bytes (250 GiB): the typed Gateway transfer tools reject it. Explain that limit; never invent a tunnel or listening service. Ordinary server-to-Gateway artifacts and staged/R2 sync transfers remain capped at 5,363,466,240 bytes (4.995 GiB).

## Mandatory reputation pre-clear contract

The intended server-to-Gateway workflow is:

1. For a directory, first create an exact archive with create_archive. The archive bytes, not the source directory representation, are the transfer artifact.
2. Call hash_file on the exact regular file or created archive with algorithm=sha256, then take the 64 lowercase hexadecimal characters after its sha256: prefix.
3. Call is_known_malicious with that 64-character value.
4. If known_malicious=true, stop before creating or uploading an artifact.
5. If known_malicious=false, call download_path with the same 64-character value as expected_sha256. This result means only "not known malicious"; it never means clean or safe.
6. Gateway independently verifies the received bytes. Asynchronous security processing may later revoke or quarantine an artifact.

For a Windows server, download_path accepts one exact drive-qualified regular file such as C:\Logs\app.log (no UNC, device, relative, or alternate-data-stream paths, and no directories). Obtain the digest with hash_file, which also accepts Windows paths, then call is_known_malicious and download_path exactly as above. The Windows host uploads the file directly to Gateway storage; Gateway executors never relay it.

## Enforced transfer boundary

This release exposes is_known_malicious and requires download_path expected_sha256. Gateway checks the digest against known-malicious evidence before reservation, independently hashes the received bytes, rejects changed or mismatched files, and rechecks malicious evidence during the durable transfer workflow.

A negative reputation lookup means only "not known malicious" at that moment. Asynchronous security processing may later add evidence, revoke the download, or quarantine the artifact. Treat Gateway links as revocable and never describe an unknown hash as clean or safe.

## Opt-in proactive s

Preview of the first 4,000 characters. Read full instructions →