---
icon: lucide/arrow-right-left
---

# transcription-proxy

Run a proxy server that forwards transcription requests to your configured ASR provider (Wyoming, OpenAI, or Gemini).

This is useful for integrating agent-cli's transcription capabilities into other applications, such as iOS Shortcuts.

## Usage

```bash
agent-cli server transcription-proxy [OPTIONS]
```

## Examples

```bash
# Run on default port
agent-cli server transcription-proxy

# Custom port
agent-cli server transcription-proxy --port 8080

# Development mode with auto-reload
agent-cli server transcription-proxy --reload
```

## Options

<!-- CODE:START -->
<!-- from agent_cli.docs_gen import all_options_for_docs -->
<!-- print(all_options_for_docs("server.transcription-proxy")) -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
### Options

| Option | Default | Description |
|--------|---------|-------------|
| `--host` | `0.0.0.0` | Host to bind the server to |
| `--port` | `61337` | Port to bind the server to |
| `--reload` | `false` | Enable auto-reload for development |


<!-- OUTPUT:END -->

## API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/transcribe` | POST | Transcribe audio file |
| `/health` | GET | Health check |
| `/docs` | GET | Interactive API documentation |

## How It Works

The transcription proxy acts as a bridge between client applications and your configured ASR provider:

```
┌─────────────────┐     ┌─────────────────────┐     ┌─────────────────┐
│  iOS Shortcut   │────▶│  Transcription      │────▶│  ASR Provider   │
│  or other app   │     │  Proxy (:61337)     │     │  (configured)   │
└─────────────────┘     └─────────────────────┘     └─────────────────┘
                                                           │
                              ┌────────────────────────────┼────────────────────────────┐
                              ▼                            ▼                            ▼
                        ┌──────────┐                 ┌──────────┐                 ┌──────────┐
                        │ Wyoming  │                 │  OpenAI  │                 │  Gemini  │
                        │ (Local)  │                 │  (Cloud) │                 │  (Cloud) │
                        └──────────┘                 └──────────┘                 └──────────┘
```

The proxy reads your agent-cli configuration to determine which ASR provider to use, then forwards transcription requests accordingly.

## Use Cases

### iOS Shortcuts Integration

The proxy provides a simple HTTP endpoint that iOS Shortcuts can call to transcribe audio. See the [iOS Shortcut Guide](../../iOS_Shortcut_Guide.md) for setup instructions.

### Custom Applications

Any application that can make HTTP requests can use the proxy to access transcription services without needing to implement provider-specific logic.

## Installation

Requires the `server` extra:

```bash
pip install "agent-cli[server]"
# or
uv sync --extra server
```

## Docker

Run using the published container image:

```bash
# Run standalone
docker run -p 61337:61337 ghcr.io/basnijholt/agent-cli-transcription-proxy:latest

# Or use docker-compose (included in both cuda and cpu profiles)
docker compose -f docker/docker-compose.yml --profile cpu up transcription-proxy
```

To use a custom config, mount it as a volume:

```bash
docker run -p 61337:61337 \
  -v ./config.toml:/home/transcribe/.config/agent-cli/config.toml:ro \
  ghcr.io/basnijholt/agent-cli-transcription-proxy:latest
```
