ts proxy

Show and manage a proxy — the SOCKS5 endpoint that launcher traffic can be routed through.

Usage

ts proxies
ts proxy <id>
ts proxy <id> <property>
ts proxy new --file=<path>
ts proxy set <id> <property> <value>
ts proxy set <id> --file=<path>
ts proxy delete <id> [--force]

Description

Proxies, sites, and routing rules are the three infrastructure entities behind the served launch policy. A proxy is the endpoint itself — a URL plus its TLS and name-resolution behavior. A site anchors to one or more proxies to say which ones can reach it, and a routing rule names the proxy that traffic for a set of sites should take. The proxy is the entity the other two reference, so create it first.

A proxy carries typed fields plus an open extra bag, so you administer it as a JSON document rather than through a flag per field. ts proxies lists the key, the URL, whether TLS is on, and the id. Every other action takes the id — the opaque GUID in the ID column — not the key.

ts proxy <id> prints the document exactly as the server stores it, and set consumes that same shape, so redirecting to a file, editing, and writing it back is a faithful round trip. new and set read the document from --file; pass - to read standard input instead. url is required on both.

For a single field there is a shorter path. ts proxy <id> <property> reads one field, and ts proxy set <id> <property> <value> writes one. The two write forms are complementary rather than alternatives: the accessor changes one field and leaves the rest of the document as it was, while --file replaces the whole document. Reach for the accessor for a one-field change — flipping tls-skip-verify in a lab, repointing url at a moved endpoint — and for --file when you are editing structure or several fields at once.

Property names are kebab-case and map to the document's camelCase key, so resolve-via-proxy addresses resolveViaProxy. Values are typed from the field being replaced — a boolean stays boolean, a numeric field stays numeric — so use-tls false writes false and not "false", and you never have to know a field's wire type. A field that is currently null is the exception: there is nothing to infer a type from, so the value goes in as a string. Use --file for a field like extra that holds an object once it is populated.

A structured field has no accessor form. A property holding an object or an array is refused, and the error points you at --file. An unknown property is refused too. Both refusals happen before anything is written, so a typo cannot half-apply.

The accessor is a read-modify-write: it fetches the document, changes the one field, and sends the whole document back. That is safe here because the document round-trips untyped, so a field this version of ts does not know about is preserved rather than dropped.

The entityKey is what site anchors and routing rules reference, so it is immutable after create. Sending a set whose entityKey differs from the stored one is rejected rather than applied, whether it arrives in a document or through the accessor. SOCKS5 is the only transport the launcher supports, so the document has no field to choose one.

ts proxy delete prompts unless you pass --force, and the server refuses the delete while any site anchor or routing rule still names the proxy. The error lists those referrers, which makes it a quick way to see what breaks before you decommission an endpoint. Reading proxies works for any signed-in account; creating, changing, and deleting them require a Server Administrator.

Options

Flag	Description	Default/Values	Notes
--file	JSON document to send.	PATH, or - for standard input	Required by new. set needs it only for the whole-document form.
--force, -f	Delete without confirming.		delete only.

Output

print writes the document and nothing else, so it pipes cleanly:

{
  "id": "1c8b40de-2f77-4a63-9f0a-5b1d3e9c8a24",
  "entityKey": "hq-socks",
  "url": "socks5://proxy.hq.example.com:1080",
  "useTls": true,
  "tlsSkipVerify": false,
  "resolveViaProxy": true,
  "extra": null
}

resolveViaProxy decides whether DNS lookups go through the proxy as well as the traffic; tlsSkipVerify disables certificate validation on the proxy connection and should stay false outside a lab. Under --format=json the document is wrapped in the standard result envelope as result.entity, which is not what set consumes — use the default text output for round trips.

A single-field read prints the bare value — true, or an unquoted URL — so it drops straight into a shell variable or an if. Under --format=json that value comes back in the envelope under the document's own key, result.useTls.

Examples

# What proxies exist, and what are their ids?
ts proxies

# One proxy as stored
ts proxy 1c8b40de-2f77-4a63-9f0a-5b1d3e9c8a24

# Just one field
ts proxy 1c8b40de-2f77-4a63-9f0a-5b1d3e9c8a24 url

# Several fields at once: the document round trip
ts proxy 1c8b40de-2f77-4a63-9f0a-5b1d3e9c8a24 > proxy.json
$EDITOR proxy.json
ts proxy set 1c8b40de-2f77-4a63-9f0a-5b1d3e9c8a24 --file=proxy.json

# Create one from standard input
cat <<'JSON' | ts proxy new --file=-
{ "entityKey": "west-socks", "url": "socks5://proxy.west.example.com:1080",
  "useTls": true, "resolveViaProxy": true }
JSON

# Flip one field — the value is typed from the field, so this writes false, not "false"
ts proxy set 1c8b40de-2f77-4a63-9f0a-5b1d3e9c8a24 use-tls false

# Repoint a proxy that moved
ts proxy set 1c8b40de-2f77-4a63-9f0a-5b1d3e9c8a24 url socks5://proxy2.hq.example.com:1080

# Gotcha: renaming is not an edit. entityKey is immutable, so a set that changes
# it is rejected — to rename, create the new proxy, repoint the sites and rules
# that reference the old key, then delete the old one.

Exit Codes

0 on success. -1 when the server rejects the document — a duplicate or changed entityKey, a missing url — and when a delete is blocked because a site anchor or routing rule still references the proxy; the message lists the referrers. -1 also covers the accessor's own refusals: a property that is not a field of the proxy, and a property holding an object or array. A single-field read of a property the document does not carry is -6 instead, the same code as an id that does not exist. -4 when no account is signed in. -5 when the account is not a Server Administrator, which affects new, set, and delete but not reads. -6 when the id is not a GUID or no proxy has it.

Related Commands

• ts routing-rule — Which sites route through this proxy.
• ts site — The locations whose anchors name a proxy.
• ts policy — The composed launch policy these entities feed.