{"slug":"tailscale-services-configuration-file","title":"Tailscale Services configuration file","tags":["tailscale","file-sharing"],"agent_summary":"Last validated: Jan 27, 2026","trigger_phrases":[],"runnable":false,"markdown":"\r\n# Tailscale Services configuration file\r\n\r\nLast validated: Jan 27, 2026\r\n\r\nThe Service configuration file defines how [Tailscale Services](https://tailscale.com/docs/features/tailscale-services) route traffic to on the devices hosting the resource associated with the Service. It contains a [`tailscale serve`](https://tailscale.com/docs/reference/tailscale-cli/serve) configuration in huJSON format. The configuration specifies Service endpoints, protocol mappings, and handler targets. It specifies which ports and protocols each Service accepts, where traffic routes, and whether to advertise Services to the Tailscale network (known as a tailnet). A Service host uses this configuration to advertise endpoints that match the Service resource definitions you've created in your tailnet.\r\n\r\nThe Service configuration file name does not matter as long as you use the correct name with the `tailscale serve` command to advertise a Service. The syntax uses `services` as the top-level field and contains an object with one or more Service definitions. Each Service definition contains an `endpoints` field that maps one or more port-protocol combinations to resources on the Service host (``).\r\n\r\n```json\r\n{\r\n \"version\": \"\",\r\n \"services\": {\r\n \"svc:\": { // is the name of the service (for example, `svc:web-server` or `svc:printer`)\r\n \"endpoints\": { // Can contain one or more endpoint mappings\r\n \":\": \"\" // Maps incoming traffic to a local target\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\nEach endpoint mapping within the `endpoints` field uses the format `protocol:port` or `protocol:start-end` for incoming traffic. Currently, only the `tcp` protocol is supported. The `` or `` defines which ports the Service listens on.\r\n\r\nThe `` defines where to forward traffic on the Service host and uses a URI-style syntax in the format `://`, where `` is one of the following:\r\n\r\n- `http`\r\n- `https`\r\n- `tcp`\r\n\r\nThis example configures an endpoint for a local web server exposed on port `443` over HTTPS:\r\n\r\n```json\r\n{\r\n \"version\": \"0.0.1\",\r\n \"services\": {\r\n \"svc:web-server\": {\r\n \"endpoints\": {\r\n \"tcp:443\": \"https://localhost:443\"\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\nThe following table describes all available fields in the Service configuration file.\r\n\r\n| Field | Level | Type | Required | Description |\r\n| --- | --- | --- | --- | --- |\r\n| `version` | Root | String | Yes | The Service configuration file format version. Must be `\"0.0.1\"`. |\r\n| `services` | Root | Object | Yes | The root object that contains one or more Services. Service names must use the format `svc:`. Each key is a service name, and each value is a service configuration object, which contains one or more endpoint mappings. |\r\n| `endpoints` | Service | Object | Yes | Contains one or more endpoint mappings for incoming traffic to local resources. |\r\n| `advertised` | Service | Boolean | No | Whether the service can accept new connections. Defaults to `true` if not specified. |\r\n\r\n![Project Logo](https://cdn.brandfetch.io/tailscale.com/fallback/lettermark/theme/dark/h/256/w/256/icon?c=1bfwsmEH20zzEfSNTed)\r\n\r\nAsk AI\r\n\r\nreCAPTCHA\r\n\r\nRecaptcha requires verification.\r\n\r\nprotected by **reCAPTCHA**\r\n","html":"

Tailscale Services configuration file

\n

Last validated: Jan 27, 2026

\n

The Service configuration file defines how Tailscale Services route traffic to on the devices hosting the resource associated with the Service. It contains a tailscale serve configuration in huJSON format. The configuration specifies Service endpoints, protocol mappings, and handler targets. It specifies which ports and protocols each Service accepts, where traffic routes, and whether to advertise Services to the Tailscale network (known as a tailnet). A Service host uses this configuration to advertise endpoints that match the Service resource definitions you've created in your tailnet.

\n

The Service configuration file name does not matter as long as you use the correct name with the tailscale serve command to advertise a Service. The syntax uses services as the top-level field and contains an object with one or more Service definitions. Each Service definition contains an endpoints field that maps one or more port-protocol combinations to resources on the Service host (<local-target>).

\n
{\r\n  \"version\": \"<version>\",\r\n  \"services\": {\r\n    \"svc:<service-name>\": { // <service-name> is the name of the service (for example, `svc:web-server` or `svc:printer`)\r\n      \"endpoints\": { // Can contain one or more endpoint mappings\r\n        \"<protocol>:<port|port-range>\": \"<local-target>\" // Maps incoming traffic to a local target\r\n      }\r\n    }\r\n  }\r\n}\n
\n

Each endpoint mapping within the endpoints field uses the format protocol:port or protocol:start-end for incoming traffic. Currently, only the tcp protocol is supported. The <port> or <start-end> defines which ports the Service listens on.

\n

The <local-target> defines where to forward traffic on the Service host and uses a URI-style syntax in the format <protocol>://<host:port>, where <protocol> is one of the following:

\n
    \n
  • http
    • \n
  • https
    • \n
  • tcp
    • \n
\n

This example configures an endpoint for a local web server exposed on port 443 over HTTPS:

\n
{\r\n  \"version\": \"0.0.1\",\r\n  \"services\": {\r\n    \"svc:web-server\": {\r\n      \"endpoints\": {\r\n        \"tcp:443\": \"https://localhost:443\"\r\n      }\r\n    }\r\n  }\r\n}\n
\n

The following table describes all available fields in the Service configuration file.

\n

| Field | Level | Type | Required | Description |\r\n| --- | --- | --- | --- | --- |\r\n| version | Root | String | Yes | The Service configuration file format version. Must be \"0.0.1\". |\r\n| services | Root | Object | Yes | The root object that contains one or more Services. Service names must use the format svc:<service-name>. Each key is a service name, and each value is a service configuration object, which contains one or more endpoint mappings. |\r\n| endpoints | Service | Object | Yes | Contains one or more endpoint mappings for incoming traffic to local resources. |\r\n| advertised | Service | Boolean | No | Whether the service can accept new connections. Defaults to true if not specified. |

\n

\"Project

\n

Ask AI

\n

reCAPTCHA

\n

Recaptcha requires verification.

\n

protected by reCAPTCHA

\n"}