How to Parse a Tailcat Token and View Its Contents as JSON

Tailcat tokens (also called ConnBlobs) are CBOR-encoded connection strings that you can decode to JSON using either the ParseConnBlobRaw function for raw CBOR data or ParseConnBlob for fully restored fields, with the CLI providing a built-in parse command for quick inspection.

Tailcat encodes connection information into tokens using CBOR serialization wrapped in base64url encoding. These tokens, identifiable by their tc prefix, contain critical mesh network data including server public keys and DERP region mappings. Whether you need to debug connectivity issues or inspect node configurations programmatically, the tailscale/tailcat repository provides both library functions and command-line tools to parse a Tailcat token and render it as readable JSON.

Understanding Tailcat Token Structure

Before parsing, it helps to understand what these tokens contain. A ConnBlob (the internal name for a Tailcat token) stores server public key material, DERP region information, node identifiers, and region routing data. The physical representation is a tc-prefixed, base-64 URL-safe string that encapsulates CBOR-encoded binary data. According to the source code in tailcat.go, this format minimizes token size while preserving cryptographic and network topology details.

Core Parsing Functions

The tailscale/tailcat library exposes two primary functions for token decoding in tailcat.go, differentiated by their field restoration behavior.

ParseConnBlobRaw for Raw CBOR Decoding

Located at lines 28-30 of tailcat.go, ParseConnBlobRaw decodes the token's CBOR payload without synthesizing additional fields. This function returns exactly what is encoded in the wire format, making it ideal for inspecting the raw stored data or when you want to avoid side effects from field reconstruction. The CLI's parse sub-command leverages this function specifically for its JSON output.

ParseConnBlob for Full Field Restoration

At lines 32-35 of tailcat.go, ParseConnBlob performs a complete decode that restores omitted fields such as RegionID and node names. This method reconstructs the full connection information structure that the encoder may have optimized away, providing a complete view of the network topology and node metadata.

Programmatic Token Parsing in Go

For applications integrating Tailcat connectivity, you can parse tokens directly using the Go API.

Decoding Raw CBOR Data

To extract the raw CBOR contents as JSON without field synthesis:

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"os"

	"github.com/tailscale/tailcat"
)

func main() {
	if len(os.Args) != 2 {
		log.Fatalf("usage: %s <token>", os.Args[0])
	}
	token := tailcat.ConnBlob(os.Args[1])

	// Decode the raw CBOR (the version the CLI “parse” command uses)
	val, err := tailcat.ParseConnBlobRaw(token)
	if err != nil {
		log.Fatalf("decode error: %v", err)
	}
	enc := json.NewEncoder(os.Stdout)
	enc.SetIndent("", "    ")
	if err := enc.Encode(val); err != nil {
		log.Fatalf("json encode error: %v", err)
	}
}

This approach uses tailcat.ParseConnBlobRaw(token) and outputs the structure using Go's standard encoding/json package with indentation.

Full Decoding with Derived Fields

To restore the complete connection information including region mappings and node identifiers:

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"os"

	"github.com/tailscale/tailcat"
)

func main() {
	if len(os.Args) != 2 {
		log.Fatalf("usage: %s <token>", os.Args[0])
	}
	token := tailcat.ConnBlob(os.Args[1])

	ci, err := tailcat.ParseConnBlob(token) // restores region & node names
	if err != nil {
		log.Fatalf("parse error: %v", err)
	}
	b, _ := json.MarshalIndent(ci, "", "    ")
	fmt.Println(string(b))
}

Here, tailcat.ParseConnBlob(token) handles the reconstruction of region IDs and node names that were elided during encoding, returning a fully populated struct suitable for marshaling to JSON.

Command-Line Token Inspection

For quick debugging without writing code, the Tailcat CLI includes a dedicated parse sub-command. Implemented in cmd/tailcat/tailcat.go at lines 56-68, this command internally calls ParseConnBlobRaw and formats the output as indented JSON.

# Suppose you have a token like "tc...."

$ tailcat parse <token>
{
    "ServerPublic": {
        "Key": "AQID... (base64‑encoded public key)",
        "LegacyKey": ""
    },
    "Region": [
        {
            "RegionID": 1,
            "RegionCode": "1",
            "Nodes": [
                {
                    "Name": "node-abc",
                    "HostName": "node-abc",
                    "RegionID": 1,
                    "Key": "AQID..."
                }
            ]
        }
    ],
    "RegionID": 1
}

The command accepts the token string directly and prints the decoded CBOR structure, including ServerPublic keys and Region arrays, to standard output.

Implementation Reference

Understanding the source layout helps when integrating these parsing capabilities:

• tailcat.go (lines 28-35): Core definitions of ConnBlob, ParseConnBlobRaw, and ParseConnBlob. Implements CBOR decode logic and region-field restoration.
• cmd/tailcat/tailcat.go (lines 56-68): CLI entry point providing the parse sub-command that consumes ParseConnBlobRaw for JSON output.
• wire.go: Defines the internal wireConnInfo struct used during CBOR unmarshalling, representing the wire format of the connection information.

Summary

• Tailcat tokens (ConnBlobs) use CBOR encoding within base64url strings prefixed with tc.
• ParseConnBlobRaw in tailcat.go returns raw CBOR-decoded data without synthesized fields, used by the CLI parse command.
• ParseConnBlob restores omitted fields like RegionID and node names for complete connection information.
• The CLI tool provides immediate JSON inspection via tailcat parse <token>, implemented in cmd/tailcat/tailcat.go.
• Both methods are available in the github.com/tailscale/tailcat package for integration into Go applications.

Frequently Asked Questions

What format does a Tailcat token use?

Tailcat tokens (ConnBlobs) are base64url-encoded strings prefixed with tc that contain CBOR-serialized connection information. This format stores server public keys, DERP region data, and node identifiers in a compact binary representation defined in wire.go and decoded via the functions in tailcat.go.

What's the difference between ParseConnBlobRaw and ParseConnBlob?

ParseConnBlobRaw (lines 28-30 of tailcat.go) decodes only the raw CBOR fields stored in the token without adding computed fields. ParseConnBlob (lines 32-35) performs the same decoding but restores omitted data such as region IDs and node names, providing a complete connection information structure suitable for full network topology reconstruction.

How do I parse a Tailcat token from the command line?

Use the tailcat parse <token> command. This CLI tool, implemented in cmd/tailcat/tailcat.go (lines 56-68), calls ParseConnBlobRaw internally and outputs the CBOR contents as formatted JSON to stdout, making it ideal for quick inspection without writing code.

What information is contained in a decoded Tailcat token?

Decoded tokens contain a ServerPublic key structure, Region arrays with DERP node details (including names, hostnames, and keys), and RegionID routing information. The exact fields available depend on whether you use raw parsing or full parsing with field restoration via ParseConnBlob.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}