### Initialize and Start Project

Source: https://github.com/deepgram-starters/bun-voice-agent/blob/main/AGENTS.md

Commands to initialize the project, set up environment variables, and start the backend and frontend servers.

```bash
# Initialize (clone submodules + install deps)
make init

# Set up environment
test -f .env || cp sample.env .env  # then set DEEPGRAM_API_KEY

# Start both servers
make start
# Backend: http://localhost:8081
# Frontend: http://localhost:8080
```

--------------------------------

### Initialize and Start Voice Agent

Source: https://github.com/deepgram-starters/bun-voice-agent/blob/main/README.md

Use the Makefile to initialize the project, configure environment variables, and start the development server.

```bash
make init
cp sample.env .env  # Add your DEEPGRAM_API_KEY
make start
```

--------------------------------

### Makefile: Start Development Servers

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Use `make start` to simultaneously launch both the backend API server (port 8081) and the frontend development server (port 8080).

```bash
# Start both backend (port 8081) and frontend (port 8080) servers
make start
```

--------------------------------

### Makefile: Initialize Project

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Run `make init` to set up the project by cloning necessary submodules and installing all project dependencies.

```bash
# Initialize project: clone submodules and install all dependencies
make init
```

--------------------------------

### Start and Stop Commands

Source: https://github.com/deepgram-starters/bun-voice-agent/blob/main/AGENTS.md

Utility commands for managing the lifecycle of the development servers.

```bash
make start
```

```bash
# Terminal 1 — Backend
bun run server.ts

# Terminal 2 — Frontend
cd frontend && bun run dev -- --port 8080 --no-open
```

```bash
lsof -ti:8080,8081 | xargs kill -9 2>/dev/null
```

```bash
rm -rf node_modules frontend/node_modules frontend/.vite
make init
```

--------------------------------

### GET /api/metadata

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Retrieves metadata about the starter application, including project details and configuration.

```APIDOC
## GET /api/metadata

### Description
Returns metadata about the starter application from the `deepgram.toml` configuration file. This endpoint is used for standardization compliance.

### Method
GET

### Endpoint
/api/metadata

### Response
#### Success Response (200)
- **title** (string) - Project title
- **description** (string) - Project description
- **author** (string) - Author information
- **repository** (string) - Repository URL
- **useCase** (string) - Primary use case
- **language** (string) - Programming language
- **framework** (string) - Framework used
- **sdk** (string) - SDK information
- **tags** (array) - List of project tags

#### Response Example
{
  "title": "Bun Voice Agent",
  "description": "Get started using Deepgram's Voice Agent with this Bun demo app",
  "author": "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)",
  "repository": "https://github.com/deepgram-starters/bun-voice-agent",
  "useCase": "voice-agent",
  "language": "typescript",
  "framework": "bun",
  "sdk": "N/A",
  "tags": ["voice-agent", "conversational-ai", "voice-ai", "voice-bot", "typescript", "bun"]
}
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/deepgram-starters/bun-voice-agent/blob/main/AGENTS.md

Standardized commit message formats for the project.

```text
feat(bun-voice-agent): add diarization support
fix(bun-voice-agent): resolve WebSocket close handling
refactor(bun-voice-agent): simplify session endpoint
chore(deps): update frontend submodule
```

--------------------------------

### Makefile: Start Frontend Server

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Run `make start-frontend` to launch only the frontend development server, useful for UI development without the backend.

```bash
make start-frontend  # Frontend dev server only
```

--------------------------------

### Function Calling Configuration

Source: https://github.com/deepgram-starters/bun-voice-agent/blob/main/AGENTS.md

Example of adding a functions array to the agent settings to enable tool use.

```json
{
  "agent": {
    "think": {
      "functions": [
        {
          "name": "get_weather",
          "description": "Get current weather",
          "parameters": { "type": "object", "properties": { "city": { "type": "string" } } }
        }
      ]
    }
  }
}
```

--------------------------------

### Makefile: Start Backend Server

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Execute `make start-backend` to run only the backend API server, typically used for API development or testing.

```bash
# Start servers individually
make start-backend   # Backend API server only
```

--------------------------------

### Makefile: Copy Environment Template

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Before starting the application, copy the `sample.env` file to `.env` and edit it to include your `DEEPGRAM_API_KEY` and other necessary configurations.

```bash
# Copy environment template and add your API key
cp sample.env .env
# Edit .env to add DEEPGRAM_API_KEY
```

--------------------------------

### Makefile: Check Prerequisites

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Use the `make check-prereqs` command to verify that essential development tools like Git and Bun are installed and accessible in your environment.

```bash
# Check prerequisites (git and bun)
make check-prereqs
```

--------------------------------

### Makefile: Clean Project

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Use `make clean` to remove all installed dependencies and build artifacts, providing a clean slate for rebuilding the project.

```bash
# Clean all dependencies and build artifacts
make clean
```

--------------------------------

### GET /health

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

A simple health check endpoint to verify the server status.

```APIDOC
## GET /health

### Description
Simple health check endpoint used by deployment platforms to verify the server is running and responsive.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - The health status of the server.

#### Response Example
{
  "status": "ok"
}
```

--------------------------------

### GET /api/session

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Issues a signed JWT session token required for authenticating WebSocket connections to the voice agent service.

```APIDOC
## GET /api/session

### Description
Issues a signed JWT session token for authenticating WebSocket connections. The token expires after 1 hour and must be included in WebSocket connection requests using the `access_token.<jwt>` subprotocol format.

### Method
GET

### Endpoint
/api/session

### Response
#### Success Response (200)
- **token** (string) - The signed JWT session token.

#### Response Example
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

--------------------------------

### Inject User Message into Conversation

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Simulate a user speaking by sending a JSON message of type 'InjectUserMessage'. This is useful for testing or guiding the conversation flow.

```javascript
// Inject a text message as if the user spoke it
ws.send(JSON.stringify({
  type: 'InjectUserMessage',
  content: 'What are your business hours?'
}));
```

--------------------------------

### Docker Build Image

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Build the Docker image for the Bun voice agent using the provided `deploy/Dockerfile`. Tag the image as `bun-voice-agent`.

```bash
# Build the Docker image
docker build -f deploy/Dockerfile -t bun-voice-agent .
```

--------------------------------

### Environment Variables Configuration

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Configure the backend server using environment variables by copying `sample.env` to `.env` and setting required values like `DEEPGRAM_API_KEY` and optional ones like `PORT` and `HOST`.

```bash
# .env file configuration

# Required: Your Deepgram API key
DEEPGRAM_API_KEY=your_api_key_here

# Optional: Backend server port (default: 8081)
PORT=8081

# Optional: Server bind address (default: 0.0.0.0)
HOST=0.0.0.0

# Optional: JWT signing secret (auto-generated in development)
# Set this in production for consistent token validation across restarts
SESSION_SECRET=your_secure_random_secret_here
```

--------------------------------

### Makefile: Run Contract Tests

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Execute `make test` to run contract conformance tests. Ensure the backend server is running before executing this command.

```bash
# Run contract conformance tests (requires running server)
make test
```

--------------------------------

### Run Tests and Verify Endpoints

Source: https://github.com/deepgram-starters/bun-voice-agent/blob/main/AGENTS.md

Commands to execute the test suite and manually verify API metadata and session endpoints.

```bash
# Run conformance tests (requires app to be running)
make test

# Manual endpoint check
curl -sf http://localhost:8081/api/metadata | python3 -m json.tool
curl -sf http://localhost:8081/api/session | python3 -m json.tool
```

--------------------------------

### Implement WebSocket Voice Agent Client

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Establishes a connection to the voice agent proxy, sends configuration settings, and handles incoming binary audio and JSON control messages.

```javascript
// Complete WebSocket voice agent client implementation
async function connectVoiceAgent() {
  // Step 1: Get session token
  const tokenResponse = await fetch('http://localhost:8081/api/session');
  const { token } = await tokenResponse.json();

  // Step 2: Connect with authentication
  const ws = new WebSocket('ws://localhost:8081/api/voice-agent', [
    `access_token.${token}`
  ]);

  ws.binaryType = 'arraybuffer';

  ws.onopen = () => {
    console.log('WebSocket connected');

    // Step 3: Send initial settings to configure the voice agent
    const settings = {
      type: 'Settings',
      audio: {
        input: { encoding: 'linear16', sample_rate: 16000 },
        output: { encoding: 'linear16', sample_rate: 16000 }
      },
      agent: {
        listen: {
          provider: { type: 'deepgram', model: 'nova-3' }
        },
        speak: {
          provider: { type: 'deepgram', model: 'aura-2-thalia-en' }
        },
        think: {
          provider: { type: 'open_ai', model: 'gpt-4o-mini' },
          prompt: 'You are a helpful voice assistant. Be concise and friendly.'
        }
      }
    };
    ws.send(JSON.stringify(settings));
  };

  ws.onmessage = (event) => {
    if (event.data instanceof ArrayBuffer) {
      // Binary audio data from agent - play through speakers
      const audioData = new Uint8Array(event.data);
      playAudio(audioData);
    } else {
      // JSON control message
      const message = JSON.parse(event.data);
      console.log('Received:', message.type, message);

      // Handle different message types
      switch (message.type) {
        case 'Welcome':
          console.log('Agent ready:', message);
          break;
        case 'UserStartedSpeaking':
          console.log('User speaking...');
          break;
        case 'AgentStartedSpeaking':
          console.log('Agent responding...');
          break;
        case 'ConversationText':
          console.log(`${message.role}: ${message.content}`);
          break;
        case 'Error':
          console.error('Agent error:', message.description);
          break;
      }
    }
  };

  ws.onerror = (error) => {
    console.error('WebSocket error:', error);
  };

  ws.onclose = (event) => {
    console.log(`Disconnected: ${event.code} ${event.reason}`);
  };

  return ws;
}

// Stream microphone audio to the agent
async function streamMicrophoneAudio(ws) {
  const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
  const audioContext = new AudioContext({ sampleRate: 16000 });
  const source = audioContext.createMediaStreamSource(stream);
  const processor = audioContext.createScriptProcessor(4096, 1, 1);

  processor.onaudioprocess = (event) => {
    if (ws.readyState === WebSocket.OPEN) {
      const inputData = event.inputBuffer.getChannelData(0);
      const pcm16 = new Int16Array(inputData.length);
      for (let i = 0; i < inputData.length; i++) {
        pcm16[i] = Math.max(-32768, Math.min(32767, inputData[i] * 32768));
      }
      ws.send(pcm16.buffer);
    }
  };

  source.connect(processor);
  processor.connect(audioContext.destination);
}
```

--------------------------------

### Check Server Health

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Verifies that the server is running and responsive.

```bash
# Check server health
curl -X GET http://localhost:8081/health

# Response:
# {
#   "status": "ok"
# }
```

--------------------------------

### Configure Function Calling for Agent

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Set up function calling capabilities for the agent by sending a 'Settings' JSON message. This includes defining the AI model, prompt, and available functions with their schemas.

```javascript
// Configure function calling for the agent
const settingsWithFunctions = {
  type: 'Settings',
  agent: {
    think: {
      provider: { type: 'open_ai', model: 'gpt-4o-mini' },
      prompt: 'You are a helpful assistant that can check the weather.',
      functions: [
        {
          name: 'get_weather',
          description: 'Get current weather for a city',
          parameters: {
            type: 'object',
            properties: {
              city: { type: 'string', description: 'City name' }
            },
            required: ['city']
          }
        }
      ]
    }
  }
};
ws.send(JSON.stringify(settingsWithFunctions));
```

--------------------------------

### Retrieve Application Metadata

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Fetches project configuration details from the deepgram.toml file.

```bash
# Request application metadata
curl -X GET http://localhost:8081/api/metadata

# Response:
# {
#   "title": "Bun Voice Agent",
#   "description": "Get started using Deepgram's Voice Agent with this Bun demo app",
#   "author": "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)",
#   "repository": "https://github.com/deepgram-starters/bun-voice-agent",
#   "useCase": "voice-agent",
#   "language": "typescript",
#   "framework": "bun",
#   "sdk": "N/A",
#   "tags": ["voice-agent", "conversational-ai", "voice-ai", "voice-bot", "typescript", "bun"]
# }
```

--------------------------------

### Makefile: Show Status

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Execute `make status` to display the current status of the main repository and all its submodules, including any uncommitted changes.

```bash
# Show repository and submodule status
make status
```

--------------------------------

### Makefile: Eject Frontend

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Run `make eject-frontend` to move the frontend code out of its submodule directory into a regular project directory, allowing for direct modification.

```bash
# Eject frontend from submodule to regular directory
make eject-frontend
```

--------------------------------

### Agent Settings Configuration

Source: https://github.com/deepgram-starters/bun-voice-agent/blob/main/AGENTS.md

JSON structure sent from the frontend to configure the agent's audio, STT, TTS, and LLM settings.

```json
{
  "type": "Settings",
  "audio": {
    "input": { "encoding": "linear16", "sample_rate": 16000 },
    "output": { "encoding": "linear16", "sample_rate": 16000 }
  },
  "agent": {
    "listen": { "provider": { "type": "deepgram", "model": "nova-3" } },
    "speak": { "provider": { "type": "deepgram", "model": "aura-2-thalia-en" } },
    "think": {
      "provider": { "type": "open_ai", "model": "gpt-4o-mini" },
      "prompt": "You are a helpful assistant."
    }
  }
}
```

--------------------------------

### Manual Endpoint Verification

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Verify API endpoints by using `curl` to fetch data from `/api/metadata` and `/api/session`, then pretty-print the JSON output using `python3 -m json.tool`.

```bash
# Manual endpoint verification
curl -sf http://localhost:8081/api/metadata | python3 -m json.tool
curl -sf http://localhost:8081/api/session | python3 -m json.tool
```

--------------------------------

### Makefile: Update Submodules

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Run `make update` to synchronize your local project's submodules with their latest commits from their respective remote repositories.

```bash
# Update submodules to latest commits
make update
```

--------------------------------

### Dynamically Update System Prompt

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Modify the agent's system prompt in real-time by sending a JSON message of type 'UpdatePrompt'. This allows for dynamic behavior changes without reconnecting.

```javascript
// Update the system prompt dynamically
ws.send(JSON.stringify({
  type: 'UpdatePrompt',
  prompt: 'You are now a technical support specialist. Help users troubleshoot issues.'
}));
```

--------------------------------

### Docker Run Container

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Run the Docker container, exposing port 8080 and setting essential environment variables like `DEEPGRAM_API_KEY` and `SESSION_SECRET`. This configuration includes Caddy for reverse proxying and rate limiting.

```bash
# Run the container
docker run -p 8080:8080 \
  -e DEEPGRAM_API_KEY=your_api_key_here \
  -e SESSION_SECRET=your_production_secret \
  bun-voice-agent
```

--------------------------------

### Update Frontend Submodule

Source: https://github.com/deepgram-starters/bun-voice-agent/blob/main/AGENTS.md

Commands to commit and push changes within the frontend submodule and update the reference in the main repository.

```bash
cd frontend && git add . && git commit -m "feat: description"
cd frontend && git push origin main
cd .. && git add frontend && git commit -m "chore(deps): update frontend submodule"
```

--------------------------------

### Handle Agent Function Call Requests

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Implement WebSocket message handling to process 'FunctionCallRequest' messages from the agent. Respond with 'FunctionCallResponse' containing the function call ID and the output.

```javascript
// Handle function call requests from the agent
ws.onmessage = (event) => {
  if (typeof event.data === 'string') {
    const message = JSON.parse(event.data);
    if (message.type === 'FunctionCallRequest') {
      // Process the function call
      const result = { temperature: '72°F', conditions: 'Sunny' };
      ws.send(JSON.stringify({
        type: 'FunctionCallResponse',
        function_call_id: message.function_call_id,
        output: JSON.stringify(result)
      }));
    }
  }
};
```

--------------------------------

### Request Session Token and Connect via WebSocket

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Retrieves a JWT session token from the backend and uses it to establish a secure WebSocket connection for the voice agent.

```bash
# Request a session token
curl -X GET http://localhost:8081/api/session

# Response:
# {
#   "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
# }

# Using the token to connect via WebSocket (JavaScript example)
const response = await fetch('http://localhost:8081/api/session');
const { token } = await response.json();

const ws = new WebSocket('ws://localhost:8081/api/voice-agent', [
  `access_token.${token}`
]);

ws.onopen = () => {
  console.log('Connected to voice agent');
  // Send settings to configure the agent
  ws.send(JSON.stringify({
    type: 'Settings',
    audio: {
      input: { encoding: 'linear16', sample_rate: 16000 },
      output: { encoding: 'linear16', sample_rate: 16000 }
    },
    agent: {
      listen: { provider: { type: 'deepgram', model: 'nova-3' } },
      speak: { provider: { type: 'deepgram', model: 'aura-2-thalia-en' } },
      think: {
        provider: { type: 'open_ai', model: 'gpt-4o-mini' },
        prompt: 'You are a helpful assistant.'
      }
    }
  }));
};
```

--------------------------------

### Live Update Messages

Source: https://github.com/deepgram-starters/bun-voice-agent/blob/main/AGENTS.md

JSON messages used to update agent behavior or send text messages during an active session.

```json
{ "type": "UpdateSpeak", "model": "aura-2-luna-en" }
```

```json
{ "type": "UpdatePrompt", "prompt": "New instructions..." }
```

```json
{ "type": "InjectUserMessage", "content": "text" }
```

--------------------------------

### Docker Container Ports and Rate Limiting

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

The Docker container exposes port 8080 and includes Caddy as a reverse proxy. It enforces rate limits: 5 requests/minute per IP for the session endpoint and 120 requests/minute per IP for API endpoints. Static frontend assets are also served by Caddy.

```bash
# The container exposes port 8080 with:
# - Caddy reverse proxy with rate limiting
# - Session endpoint: 5 requests/minute per IP
# - API endpoints: 120 requests/minute per IP
# - Static frontend assets served by Caddy
```

--------------------------------

### Update TTS Voice Mid-Conversation

Source: https://context7.com/deepgram-starters/bun-voice-agent/llms.txt

Send a JSON message of type 'UpdateSpeak' to change the Text-to-Speech voice during an active conversation. Ensure the specified model is available.

```javascript
// Update the TTS voice during conversation
ws.send(JSON.stringify({
  type: 'UpdateSpeak',
  model: 'aura-2-luna-en'  // Change to a different voice
}));
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.