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

# Your First TCP Monitor

> Create your first DevHelm TCP monitor to verify port connectivity

By the end of this guide, you'll have a TCP monitor verifying that your service is accepting connections on a specific port.

<Accordion title="Prerequisites">
  * DevHelm CLI installed or an API token for REST calls
  * An API token set as `DEVHELM_API_TOKEN` — see [Authentication](/authentication)
  * A host and port that accepts TCP connections
</Accordion>

## Create the monitor

<Steps>
  <Step title="Create the TCP monitor">
    <CodeGroup>
      ```bash CLI theme={null}
      devhelm monitors create \
        --name "Database Port" \
        --type TCP \
        --url db.example.com \
        --port 5432 \
        --frequency 60 \
        --regions us-east
      ```

      ```yaml devhelm.yml theme={null}
      version: "1"
      monitors:
        - name: Database Port
          type: TCP
          config:
            host: db.example.com
            port: 5432
            timeoutMs: 5000
          frequencySeconds: 60
          regions:
            - us-east
      ```

      ```bash API theme={null}
      curl -X POST https://api.devhelm.io/api/v1/monitors \
        -H "Authorization: Bearer $DEVHELM_API_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "Database Port",
          "type": "TCP",
          "config": {
            "host": "db.example.com",
            "port": 5432,
            "timeoutMs": 5000
          },
          "frequencySeconds": 60,
          "regions": ["us-east"]
        }'
      ```
    </CodeGroup>
  </Step>

  <Step title="Verify it's running">
    ```bash theme={null}
    devhelm monitors list --type TCP
    devhelm monitors get <monitor-id>
    ```
  </Step>

  <Step title="Check results">
    Results show whether the TCP connection was established and the connection time in milliseconds.

    ```bash theme={null}
    devhelm monitors checks <monitor-id> --limit 5
    ```
  </Step>
</Steps>

## Add assertions

<CodeGroup>
  ```yaml devhelm.yml theme={null}
  monitors:
    - name: Database Port
      type: TCP
      config:
        host: db.example.com
        port: 5432
      frequencySeconds: 60
      regions:
        - us-east
      assertions:
        - config:
            type: tcp_connects
          severity: fail
        - config:
            type: response_time
            thresholdMs: 1000
          severity: warn
  ```
</CodeGroup>

Available TCP assertions:

| Type            | What it checks                                            |
| --------------- | --------------------------------------------------------- |
| `tcp_connects`  | Connection is established within the timeout              |
| `response_time` | Connection completes within a threshold                   |
| `tcp_banner`    | The server's initial response matches an expected pattern |

For details, see [TCP configuration](/monitoring/tcp/configuration).

## Common use cases

<AccordionGroup>
  <Accordion title="Database connectivity">
    Monitor PostgreSQL (5432), MySQL (3306), Redis (6379), or any database port to detect connection issues before they affect your application.
  </Accordion>

  <Accordion title="Internal service ports">
    Verify that microservices are accepting connections on their expected ports — useful for service mesh health checks.
  </Accordion>

  <Accordion title="SMTP/mail servers">
    Check that your mail server is accepting connections on port 25, 465, or 587.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="TCP monitor reference" icon="network-wired" href="/monitoring/tcp/overview">
    Full TCP configuration and assertion details.
  </Card>

  <Card title="First alert" icon="bell" href="/guides/first-alert">
    Get notified when the TCP connection fails.
  </Card>

  <Card title="Monitors guide" icon="signal" href="/guides/monitors">
    Configure all six monitor types.
  </Card>
</CardGroup>