Gateman
Documentation/Using Gateman with coding agents

Using Gateman with coding agents

Gateman lets an application use supported provider capabilities without giving a coding agent the underlying provider credentials. The agent works against Gateman's authenticated, application-scoped interface while Gateman keeps configured provider credentials inside its protected storage.

Gateman is not a universal provider proxy or an IAM replacement. Each capability has its own routes, payload, provider behavior, and limits. Provider permissions remain authoritative, and Gateman only authorizes capabilities enabled for the application.

What each participant does

The developer controls the application and its authorization:

  • Create or select the Gateman application.
  • Enable the required capabilities.
  • Configure the provider credentials and settings in the Gateman console.
  • Obtain and protect the application's signing material.
  • Give the coding agent the appropriate setup instructions.
  • Control deployment, environment selection, and production authorization.

The coding agent implements the application integration:

  • Select the Official client for the application's language.
  • Configure the client from application-controlled runtime configuration.
  • Authenticate and retrieve the current application context.
  • Read the Capability Reference for the enabled operation.
  • Implement, test, and handle the documented response and failure behavior.

The developer decides the application's architecture, provider choices, and whether existing application code is retained, removed, or replaced. Gateman defines the authorized capability contracts and their provider-specific request, response, and failure behavior; it does not prescribe the application's internal design.

Gateman authenticates application requests, enforces application capability scopes, uses configured provider credentials for supported operations, and returns the current application integration context. Gateman does not create or authorize application credentials on behalf of an agent.

Application signing credentials are separate from provider credentials. The agent must not receive provider keys merely because it is implementing a provider-backed feature, and the application must still protect its own HMAC secret or Ed25519 private key.

End-to-end workflow

  1. Configure the Gateman application in the console.
  2. Enable the capability the application needs.
  3. Configure the relevant provider credentials in Gateman.
  4. Obtain the console-generated bootstrap instructions.
  5. Install the application's language-specific [Official client](https://docs.getgateman.com/canonical-client-php/).
  6. Load the Gateman application configuration into the server-side runtime.
  7. Authenticate with Contract v1 and request POST /client/get.
  8. Identify the enabled capability, its required scope, routes, and linked documentation.
  9. Follow the selected Capability Reference.
  10. Implement and test the operation using the client's generic request method.
  11. Optionally copy stable, non-secret guidance into the project's AGENTS.md integration.

The bootstrap prompt supplies connection setup. The authenticated /client/get response supplies current application-specific capability context. See Bootstrap context for that handoff.

Different capability models

Gateman capabilities do not all operate in the same way:

  • A provider-native relay sends a bounded request through Gateman, such as the supported AWS or Cloudflare administrative relays. The provider's own permissions still decide whether the operation is allowed.
  • S3 and R2 presigning returns a signed request. Object bytes transfer directly between the application and the storage provider; Gateman does not proxy the object body.
  • Email and SMS capabilities submit provider-native messages or capture them according to the documented application environment behavior.
  • Provisioning capabilities perform a specific setup action needed by a supported capability. They are not general infrastructure management.
  • Explicit credential-retrieval capabilities can return an authorized value, but only when their separate scope and provider retrieval settings allow it. Credential retrieval is not the normal implementation path for a supported relay or presigning capability.

Read the selected Capability Reference before choosing an integration model.

A practical instruction for a coding agent

A developer can provide an agent with an instruction such as:

Use the Gateman application configuration already supplied to this server-side
application. Use the Official client for this language, authenticate with
Contract v1, and call POST /client/get. Implement the developer's requested
functionality using the capabilities authorized for this application and
relevant to that task. Read each selected capability's linked Capability
Reference and preserve its provider-native request, error, retry, idempotency,
and environment rules. Do not expand the task to implement every authorized
capability.
Do not request or add provider credentials. Keep Gateman signing material in
server-side runtime configuration and out of source, logs, prompts, and browser
code.

The exact application ID, base URL, authentication mode, and signing material belong in the application's protected setup and runtime configuration. They are not supplied by this generic project instruction.

Boundaries and first-request checks

An absent capability in /client/get means the application is not currently authorized for it. A configured provider credential name does not prove that the provider is ready, and an enabled capability does not make every provider or operation available. Use the documented route and payload; do not invent a universal helper or provider operation.

For authentication and response handling, see Authentication, Contract v1, and Errors and responses. Use Environments for application environment behavior.