> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hexr.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway Service

> Tool registry and credential-injecting proxy. Connects agents to 150+ external APIs with automatic authentication.

## What It Does

The Hexr Gateway is the single entry point for all external tool calls. When an agent calls `hexr_tool("aws_s3", ...)`, the request flows through the Gateway, which:

1. **Resolves** the tool name to an API endpoint
2. **Injects credentials** from the Credential Injector
3. **Forwards** the authenticated request to the target service
4. **Records** telemetry (spans, metrics) for observability

***

## Tool Registration

Tools are registered via three mechanisms:

| Method             | Description                                     |
| ------------------ | ----------------------------------------------- |
| **Built-in**       | Pre-registered cloud services (AWS, GCP, Azure) |
| **OpenAPI import** | Register any OpenAPI spec                       |
| **MCP discovery**  | Connect MCP-compatible tool servers             |

***

## Pre-loaded Tools

| Service       | Tool Name          | Provider |
| ------------- | ------------------ | -------- |
| S3            | `aws_s3`           | AWS      |
| DynamoDB      | `aws_dynamodb`     | AWS      |
| SQS           | `aws_sqs`          | AWS      |
| Lambda        | `aws_lambda`       | AWS      |
| BigQuery      | `gcp_bigquery`     | GCP      |
| Cloud Storage | `gcp_storage`      | GCP      |
| Pub/Sub       | `gcp_pubsub`       | GCP      |
| Blob Storage  | `azure_storage`    | Azure    |
| Cosmos DB     | `azure_cosmosdb`   | Azure    |
| Service Bus   | `azure_servicebus` | Azure    |
| GitHub API    | `github`           | SaaS     |
| Slack API     | `slack`            | SaaS     |

***

## Request Flow

<Steps>
  <Step title="Agent calls hexr_tool()">
    Your agent calls `hexr_tool("aws_s3")` which invokes `s3.list_buckets()`. The request goes to the Gateway via Envoy.
  </Step>

  <Step title="Gateway resolves tool">
    The Gateway resolves `aws_s3` to the S3 endpoint and validates the request.
  </Step>

  <Step title="Credential exchange">
    The Gateway calls the Credential Injector to exchange the caller's SPIFFE identity for temporary AWS credentials.
  </Step>

  <Step title="API call with credentials">
    The Gateway calls `ListBuckets` on the S3 API using SigV4 signing with the temporary credentials.
  </Step>

  <Step title="Response with telemetry">
    The API response is returned to the agent. A telemetry span is recorded for the entire request lifecycle.
  </Step>
</Steps>

```
Agent → Gateway → Credential Injector (SPIFFE → AWS creds) → S3 API → Response → Agent
```

***

## API Endpoints

| Method | Path                          | Description                 |
| ------ | ----------------------------- | --------------------------- |
| `GET`  | `/api/v1/tools`               | List all registered tools   |
| `GET`  | `/api/v1/tools/:name`         | Get tool details            |
| `POST` | `/api/v1/tools/:name/execute` | Execute a tool call         |
| `POST` | `/api/v1/tools/register`      | Register new tool (OpenAPI) |
| `GET`  | `/api/v1/tools/search`        | Search tools by name/tag    |
| `GET`  | `/health`                     | Health check                |

***

## Configuration

| Environment Variable      | Default                                 | Description                    |
| ------------------------- | --------------------------------------- | ------------------------------ |
| `CREDENTIAL_INJECTOR_URL` | `http://cred-injector.hexr-system:8080` | Credential Injector endpoint   |
| `VALKEY_URL`              | `valkey.hexr-system:6379`               | Tool registry cache            |
| `LISTEN_ADDRESS`          | `:8080`                                 | HTTP listen address            |
| `MAX_TOOL_TIMEOUT`        | `30s`                                   | Maximum tool execution timeout |

***

## Image

```
us-central1-docker.pkg.dev/hexr-cloud-prod/hexr-images/hexr-gateway:v0.4.1
```