# 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: ```text APP_ENVIRONMENT=production GM_APP= GM_BASE_URL= GM_PRIVATE_KEY= ``` 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: ```text GET /client/php GET /client/node GET /client/python GET /client/go ``` The current clients have equal standing: - [PHP client](https://docs.getgateman.com/canonical-client-php/) — PHP 8.3+ with cURL and JSON; sodium is required for Ed25519. - [Node.js client](https://docs.getgateman.com/canonical-client-node/) — Node.js 22+, ESM, locally installed from the distributed archive. - [Python client](https://docs.getgateman.com/canonical-client-python/) — Python 3.11+, synchronously installed from the distributed archive. - [Go client](https://docs.getgateman.com/canonical-client-go/) — 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: ```http 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: ```text 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](https://docs.getgateman.com/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](https://docs.getgateman.com/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. ## Related references - [Using Gateman with coding agents](https://docs.getgateman.com/using-gateman-with-coding-agents/) - [AGENTS.md integration](https://docs.getgateman.com/agents-md-integration/) - [Contract v1](https://docs.getgateman.com/contract-v1/) - [Authentication](https://docs.getgateman.com/authentication/) - [Environments](https://docs.getgateman.com/environments/) - [Errors and responses](https://docs.getgateman.com/errors-and-responses/) - [Official PHP client](https://docs.getgateman.com/canonical-client-php/) - [Official Node.js client](https://docs.getgateman.com/canonical-client-node/) - [Official Python client](https://docs.getgateman.com/canonical-client-python/) - [Official Go client](https://docs.getgateman.com/canonical-client-go/) - [Public configuration](https://docs.getgateman.com/public-configuration/)