Gateman
Documentation/Bootstrap context

Bootstrap context

Bootstrap context is the application-specific setup needed to establish a Gateman connection. It is not a public capability snapshot and it is not a separate /bootstrap or /context API endpoint.

Three information boundaries

Public bootstrap resources are available before application authentication:

  • Public Gateman documentation and Capability References.
  • The four Official client artifacts.
  • The published Contract v1 and client guides.

Application bootstrap configuration is supplied for the selected application:

  • Gateman application identifier.
  • Gateman base URL.
  • Authentication mode and one-time application signing material.
  • The console-generated setup instructions and .gateman template.

Authenticated application context is returned only after a valid Contract v1 request:

  • Current authorized scopes and enabled capabilities.
  • Safe provider configuration metadata.
  • Environment behavior.
  • Current ordered implementation rules.
  • Capability documentation URLs.

Provider credentials configured in Gateman remain protected there. They are not part of the bootstrap prompt or the /client/get response.

Obtain the console-generated setup

Open the Gateman application's setup materials in the console and copy the AI-agent bootstrap prompt and the .gateman template. The prompt contains the application-specific connection facts, authentication mode, a placeholder for the one-time signing credential, Official client acquisition guidance, and the instruction to call POST /client/get after authentication succeeds.

It does not contain the current capability list or implementation rules. Those are retrieved from /client/get so that they reflect current application state. If scopes or capabilities change, call /client/get again; regenerating the prompt is unnecessary.

The developer must obtain and protect the one-time signing material. The coding agent can implement configuration loading and the request flow without seeing the actual signing material. The developer or deployment process controls that material; the agent cannot independently create, rotate, or authorize the application's Gateman credentials.

Application configuration

The console-generated template uses this syntax:

APP_ENVIRONMENT=production
GM_APP=<application ID>
GM_BASE_URL=<Gateman base URL>
GM_PRIVATE_KEY=<copy from the one-time credential display>

HMAC applications use GM_APP_SECRET instead of GM_PRIVATE_KEY. APP_ENVIRONMENT may be set to production, staging, or development by the application's deployment configuration. Gateman does not choose the application's runtime environment.

The application or deployment process must load this file into the server-side process environment. Official clients do not automatically discover .gateman or .env files: PHP's canonical client reads the configured process environment, while Node.js, Python, and Go clients receive configuration explicitly through their constructors. See the language-specific client guide for the exact constructor or configuration type.

A populated .gateman file and application signing material must not be committed, logged, served as a web asset, placed in browser code, or copied into reusable project instructions.

Acquire an Official client

The artifacts are public and can be acquired before authentication:

GET /client/php
GET /client/node
GET /client/python
GET /client/go

The current clients have equal standing:

  • PHP client — PHP 8.3+ with cURL and JSON; sodium is required for Ed25519.
  • Node.js client — Node.js 22+, ESM, locally installed from the distributed archive.
  • Python client — Python 3.11+, synchronously installed from the distributed archive.
  • Go client — Go 1.26+, incorporated from the distributed source archive.

These are direct Gateman distribution routes. Do not assume a public Composer, npm, PyPI, or Go module publication. The client guides describe the supported local installation conventions.

Retrieve current application context

After configuring an Official client, make the authenticated request:

POST /client/get
Content-Type: application/json

{}

An empty body or [] is also accepted. The endpoint requires Contract v1 authentication and the client:read scope. It is not publicly accessible and does not require a credential-disclosure request identifier.

The response has this top-level shape:

ok
snapshot
application
global_rules
capabilities

application contains the application ID, authentication mode, and authorized scopes. Each capabilities entry contains:

  • id, required_scopes, and routes;
  • providers_with_credential_names;
  • provider_configuration, including credential-name presence, retrieval permission, and a not_evaluated readiness value;
  • environment, including its source, accepted values, and behavior;
  • ordered implementation_rules; and
  • documentation, containing the full public Capability Reference URL.

Capabilities are filtered by the application's current runtime scopes. Names of configured credentials may be reported, but credential values are not. Provider configuration metadata is not a provider readiness check. The context does not return client source or reusable AGENTS.md blocks.

Troubleshoot the connection

  • Missing or invalid application material, a stale timestamp, or an invalid signature is an authentication problem. Compare the request with [Contract v1](https://docs.getgateman.com/contract-v1/) and Authentication.
  • A missing client:read scope prevents context retrieval even when other capabilities are enabled.
  • Check the configured base URL, request method, exact path, and raw signed body. Do not sign one body and send another.
  • If a capability is absent, confirm its scope is enabled for this application; do not infer availability from a public Capability Reference.
  • If a capability is present but a provider is unavailable, inspect its provider configuration and follow the capability's documented error behavior.
  • A configured source-IP restriction can reject an otherwise valid request.

Use Errors and responses for shared status behavior. Do not bypass Contract v1 or request provider credentials as a connection workaround.

After bootstrap

Use the returned capability entries to select an authorized operation, open its linked Capability Reference, and call its documented route with the Official client's generic authenticated request method. The clients do not provide invented provider-specific convenience helpers. Interpret the actual HTTP and provider-native response according to the selected capability contract.