Build through a controlled path.

Gated evaluates an agent’s requested action against workspace policy, asks a human for approval when required, and executes through bounded server-held authority. The verified live private preview creates a new GitHub branch at an exact existing commit in a selected non-critical repository.

Only actions routed through Gated-controlled tools and credentials are governed. Direct GitHub access can bypass Gated. This is not universal interception or production-ready software.

Use the existing Pilot setup and downloadable onboarding packet. The packet contains the current step-by-step instructions for the independent rehearsal.

1. Create and confirm your account or use the offered GitHub/Google sign-in. Sign in and create a workspace. Enroll a passkey and an independently usable second authenticator; if authenticator-app MFA is enabled, complete it at sign-in.
2. Connect GitHub: install Gated Approval Proof on only your chosen non-critical repository, complete passkey and GitHub authorization, then choose the verified repository. You must administer the repository.
3. Save an approval-required policy for github.branch.create and the connected resource. The initial empty policy denies all actions. Create a short-lived agent token restricted to that repository and action. Keep it in the runtime’s protected environment.
4. Download and review the installer linked below. Install the matching project skill, then explicitly invoke it with the repository resource, exact existing 40-character SHA and unique gated/ branch name.
5. Submit a request. Review its exact details in Approvals and approve with a passkey if policy permits. Execute the same saved request after approval.
6. Inspect the result in GitHub and compare the exact branch and commit. Inspect Activity, Action Graph and Operations; revoke the test agent when done. Do not repeat an uncertain write with a new request.

The operation’s current environment field is “production.” This is the schema’s request classification; use a non-critical repository. Branch creation can still trigger repository automation, so choose the repository carefully.

Agent

An identity with a revocable, scoped Gated token. The runtime label is descriptive, not identity attestation.

Action

The specific proposed operation. The live pilot supports github.branch.create.

Resource

The selected provider object; GitHub repositories use github:<numeric repository ID>.

Environment

Policy context carried by a request; the current GitHub schema accepts production.

Policy

Versioned workspace rules deciding ALLOW, REQUIRE_APPROVAL or DENY.

Approval

A human decision bound to one immutable request, payload hash and policy version.

Execution

The separately claimed attempt to perform an authorized request through the provider adapter.

Activity / Action Graph

Stored request/decision and linked policy, approval, execution and credential-lifecycle evidence.

Shadow Mode

Explicitly submitted observations evaluated against policy without authorization or execution.

GitHub private preview

Supported: create one unique gated/ branch at an exact existing SHA through a verified GitHub App binding. The server requests temporary authority for one repository with Contents write, validates repository/scope/expiry, executes the saved ref/SHA, records the response and attempts revocation. Contents write is broader than branch creation; the trusted executor narrows the operation.

A hosted live proof and independent provider readback passed. Replay returns the existing execution; revoked agents are rejected. PR merge, force push, branch update/deletion and a generic GitHub proxy are not implemented. Revocation blocks future requests/claims; it cannot recall a call already in flight or remove credentials held outside Gated. Failed cleanup is visible as uncertainty, not successful revocation.

Codex

The downloaded project skill explicitly invokes the bundled Gated CLI. Use $gated-github. Actual Codex safe-mode request, approval, simulated execution, replay and token-revocation checks passed. Live GitHub execution was separately verified through the downloaded CLI. This is not native automatic interception of every Codex tool.

Claude Code

The downloaded project skill invokes the same controlled CLI path. Use /gated-github. The actual Claude Code safe-mode rehearsal passed; its runtime rehearsal did not make a live GitHub write. The skill does not universally intercept tools or block direct provider credentials.

AWS and Vercel adapters are foundations; live pilot support is not verified. Other integrations are Planned. No new SDK or integration is implied.

Rules contain id, identities, actions, resources, environments, outcome and reason; optional utcHours and gitShas narrow matching. Identities support explicit UUIDs or *, actions use the supported schema, resource IDs are exact, and UTC hours use database time. The schema also contains vercel.deploy and aws.lambda.promote for existing adapter foundations; only github.branch.create has the stated live pilot proof.

DENY takes precedence over REQUIRE_APPROVAL, which takes precedence over ALLOW. No match denies. Approval does not override a hard deny. Use a narrow approval-required rule for the first non-critical GitHub workflow.

Policy versions are archived. An unexecuted request made under an older version is invalidated after a policy change. Execution rechecks policy context, scope, workspace stop and credential/connection revocation before obtaining a claim. Changing a policy does not rewrite old audit evidence.

In Policies, or after selecting an agent and repository in Pilot setup, choose a starting policy. Strict requires human approval for supported writes and is the initial selection. Checkboxes prepare a draft only: inspect the exact JSON, customize it, then save to confirm. Drafts preserve other rules; incompatible profiles are rejected. A stale draft cannot overwrite a newer policy.

• Repository write lock: DENY github.branch.create. Repository reads are not mediated yet.
• Branch developer: ALLOW supported gated/ branch creation at existing commits.
• Release assistant and Strict: REQUIRE_APPROVAL for github.branch.create in production. These two profiles may be combined.
• Observe only: DENY branch execution for the selected scope. Record scenarios separately using Shadow Mode. Shadow results never authorize execution.

Each rule names one agent, exact repository and the production environment. Preset source, IDs and version are stored as rule origin metadata in normal immutable policy history. Metadata explains provenance; the ordinary evaluator determines decisions. Deny and approval precedence still apply across all rules. Read operations, feature/* or protected-branch matching, staging-class environments and destructive actions are not supported by these packs.

Gated MCP helps agents understand policy. Trusted integrations enforce policy. The stateless JSON-response MCP endpoint is POST /api/mcp/:workspaceId. Configure a client that supports custom Authorization headers with its existing scoped Gated agent Bearer token, injected from protected runtime storage. No provider credential is returned. This initial endpoint uses pre-issued Gated tokens, not OAuth discovery. MCP protocol revisions 2025-11-25 and 2025-06-18 are supported; it does not offer a standalone SSE stream.

Initialize the client, discover tools with tools/list, then call get_current_agent_identity, list_my_allowed_actions, get_policy_for_resource, get_constraints, check_action or explain_decision. The action list is a scoped rule summary, including conditional rules and denies; it is not a blanket list of executable permissions. Check an exact payload containing action, resource, environment, branch and gitSha. GitHub accepts only gated/ branch names and production classification.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "check_action",
    "arguments": {
      "payload": {
        "action": "github.branch.create",
        "resource": "github:123",
        "environment": "production",
        "branch": "gated/oauth-fix",
        "gitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
      }
    }
  }
}

The structured result includes advisory_decision (ALLOW, REQUIRE_APPROVAL or DENY), matched_rule, reason, policy_version, constraints, evaluated_at, an ephemeral decision_id, enforcement_required: true, executable: false and persisted: false. A check creates no request, approval, execution or provider credential. Recheck when context changes. Read-only checks are rate limited and are not added individually to Action Graph or durable audit.

Request human approval intentionally

request_approval takes the full existing GitHub request payload—including nonce, issuedAt and task context—and a UUID idempotencyKey. It calls the same Gated request transaction as the CLI. Retry only the same complete payload and key; changed parameters conflict. Hard deny stays denied, approval-required becomes pending, and allow creates a normally authorized request without unnecessary human review. Request expiry, exact parameter binding, human reviewer roles and passkey checks remain unchanged. There is no agent self-approval tool.

get_approval_status takes the request UUID as id and returns request_id, decision, approval_status, expires_at, policy_version, current_policy_version, policy_changed and a current_advisory check. Poll at intervals of at least five seconds; status calls are limited to 12 per minute per agent. A recorded approval may be stale after a policy change. Neither tool executes a provider action. Use the existing trusted execution path for a separately authorized claim.

Revoked or expired agents lose access on subsequent calls, including tool discovery. Workspace and resource scope are enforced server-side. MCP request provenance appears in the existing request audit and Action Graph. Direct provider credentials can bypass Gated if not removed or contained.

In Policies, Generate suggestions analyzes recorded human decisions and explicit Shadow observations. The engine is deterministic and recommendation-only: it never automatically changes enforcement policy and uses no LLM. Review a suggestion, inspect its exact generated rule and evidence, replay the impact, then accept to create a normal policy version. Dismiss, snooze for seven days, or suppress that exact pattern permanently.

A comparable group must contain at least ten records from ten distinct task IDs during the last 30 days, for one agent, repository, production environment and exact commit. Operator Shadow scenarios, agent Shadow observations and human-reviewed requests are grouped separately. The bounded scan includes up to 1,000 recent records per source; groups exceeding 200 records are deferred so displayed evidence is complete. Task IDs are self-reported and are not proof of independent users or outcomes.

Unanimous human denials can suggest DENY. Repeated observations or unanimous human approvals can suggest an explicit REQUIRE_APPROVAL rule where replay changes current decisions. These signals do not establish provider success. Failed, unknown or incomplete execution records are excluded from reviewed-request evidence; unexecuted human reviews remain labeled as decisions. Shadow scenarios are never called approvals or successful actions.

Each suggestion includes count, source, first/last timestamps, recorded policy and human outcome distributions, historical policy versions, exact scope, proposed rule, and before/after replay using the existing evaluator at each recorded timestamp. Replay is a policy counterfactual, not a prediction of external execution or current provider state.

Acceptance appends the exact reviewed rule under a policy-version check and existing human management/passkey requirements. It never removes or weakens a hard deny and never proposes ALLOW in this version. Suggestions become stale when the policy, agent or connection changes. The scope stays pinned to one agent, repository and commit; because branch-prefix matching is unsupported, the rule applies to all supported gated/ branch names at that commit. Humans must consider this scope before accepting. Generation, viewing, dismissal/snooze/suppression, acceptance and resulting policy versions enter audit history.

Inspect the exact repository, action, environment, branch, SHA, task context and policy decision. A current authorized owner/admin/approver uses a passkey step-up bound to the request; the agent cannot approve itself. An authenticator-app sign-in challenge does not replace the passkey approval.

Requests expire 15 minutes after creation. Approval is tied to the immutable request and policy version; the one-use passkey authorization has its own short validity window. A denial is terminal, and changing the payload requires a new intended operation—not a retry of an uncertain execution.

Approval authorizes a later claim. It does not itself create the branch or guarantee provider success. Policy changes and revocation can prevent execution after approval.

Activity records requests, policy decisions and execution results. Action Graph v1 links a selected request with its agent, archived policy, approval, execution and credential/reconciliation evidence. Audit hashes detect changes within the recorded chain; a filtered graph is not independent verification of the entire history and does not prove causality outside Gated. Lists are bounded; absence from a recent list is not proof that an older record never existed.

• ALLOW / REQUIRE_APPROVAL / DENY: authorization decisions.
• SIMULATED: no live provider write.
• SUBMITTED: provider returned the expected response; separately verify the branch/SHA in GitHub.
• FAILED: recorded failure; inspect the reason.
• UNKNOWN or an unresolved CLAIMED execution: reconciliation is required. Do not create a replacement request or retry a direct write.

Credential evidence distinguishes issuance, attempted cleanup and confirmed or uncertain revocation without exposing the credential value. Consult Operations for unresolved cleanup and monitoring alerts.

Shadow Mode

Shadow Mode evaluates explicitly instrumented Gated requests against policy and stores immutable observations. Even an ALLOW observation cannot authorize execution, obtain a credential or become an executable request. It does not passively observe all external actions or block tools outside Gated. Operator scenarios are labeled separately from agent observations.

Use non-critical private-pilot workflows. Keep provider tokens, Gated agent tokens, passwords and recovery material out of prompts, transcripts, task context and source control. Scope the GitHub App to the test repository and keep direct-provider bypass in mind.

Passkeys, authenticator-app MFA, session management, workspace stop and agent revocation exist. In-flight provider calls cannot be recalled. UNKNOWN and cleanup failures require operator review; do not treat them as safe to retry.

Encrypted off-primary backups and failure alerts have been tested. Native Cloudflare monitoring has run successfully; actual GitHub scheduled backup capture proof is still open, and full replacement-service recovery is intentionally deferred until a separate environment is ready. Gated is operated by Jasper Dragoo as an individual; no guaranteed support response, SLA, compliance certification or production-readiness promise. Agree data retention and recovery expectations before pilot use.

Support: support@gated.sh. Security: security@gated.sh. Privacy/export/deletion: privacy@gated.sh.

This is the implemented narrow CLI—not a promised SDK. Review gated-agent-setup.mjs, and the shell preflight, save both in the same folder, then run ONE command matching your runtime (macOS/Linux, Node 24):

sh gated-agent-preflight.sh ./gated-agent-setup.mjs codex /absolute/path/to/project
sh gated-agent-preflight.sh ./gated-agent-setup.mjs claude-code /absolute/path/to/project

The preflight checks Node availability/version, executable and installer paths, including macOS temporary-directory aliases. It explains recovery and never installs Node. The installer puts gated-github in .agents/skills or .claude/skills for that project and refuses to overwrite an existing skill. If Node is missing or old, install Node 24 from the official Node download page, reopen the terminal and rerun. Standard macOS installation locations are checked even without PATH. Use an existing project directory, or create one with mkdir -p ~/gated-pilot. Copy the exact protected-session command from Pilot setup and paste the scoped token at its hidden prompt. It checks API access and workspace/token validity, then opens a shell with the commands below. Launch your coding client there, and type exit when done. Automated clients may inject GATED_API_ORIGIN, GATED_ORG_ID and GATED_AGENT_TOKEN through a protected process environment. Never print the environment or put a token in a command example, request file or prompt.

gated doctor
gated prepare <file> <resource> <branch> <sha> <runtime> "<intent>"
gated submit <file>
gated status <file>
gated execute <file>

Replace placeholders with your actual values. Runtime is codex, claude-code or other. Prepare refuses overwrite; submit within five minutes. Keep the same private, untracked request file and idempotency key for retries. Execute only after approval when required; UNKNOWN needs reconciliation.

Use the CLI to construct the verified GitHub request rather than improvising a payload. Human endpoints require a current session and membership; mutable browser requests require the exact console origin. The approval UI performs the passkey ceremony; this reference does not offer a shortcut around it.