ts proxy

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

Usage

ts proxies [--csv] [--no-trunc]
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, and its scheme is the proxy's type.

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. It then reads the field back and fails if the server did not keep the value.

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.

The document has no field for the proxy's type: the type is the scheme of its url, socks5://, http://, or https://, and the URL must name a port, even the scheme's usual one (https://proxy.example.com:443, not https://proxy.example.com). The server reads the type each time the proxy is created or saved, so a set that keeps the URL keeps the type, and one that changes the scheme changes it: ts proxy set <id> url http://proxy.example.com:3128 makes the proxy an HTTP proxy. A URL the server cannot read a type from — another scheme, no host, or no port — is refused, and nothing is saved:

Error: url must be a socks5, http or https URL that names a host and a port, such as socks5://proxy.example.com:1080.

ts proxy delete prompts unless you pass --force, and the server refuses the delete while any site anchor, routing rule, or network access 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. Required when there is no terminal.
--csv	Tab-separated output, nothing truncated.		ts proxies only.
--no-trunc	Do not truncate columns.		ts proxies 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

# Make it an HTTP proxy: the scheme is the type
ts proxy set 1c8b40de-2f77-4a63-9f0a-5b1d3e9c8a24 url http://proxy.hq.example.com:3128

# 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.

# A URL with no port is refused, even for the scheme's usual port. Write :443.
ts proxy set 1c8b40de-2f77-4a63-9f0a-5b1d3e9c8a24 url https://proxy.hq.example.com

Exit Codes

0 on success. -1 when the server rejects the document — a missing, duplicate or changed entityKey, a missing url, or a url that is not a socks5, http, or https URL naming a host and a port — when a delete is blocked because a site anchor, routing rule, or network access rule still references the proxy, in which case the message lists the referrers, and when an accessor write does not read back as the value sent. -2 when the property holds an object or array, and when set is given both a property and --file. -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, when a property, read or written, is not a field of the proxy, and when the --file path does not exist.

Related Commands

• ts routing-rule — Which sites route through this proxy.
• ts site — The locations whose anchors name a proxy.
• ts network-rule — Network access rules, which can also name a proxy.
• ts policy — The composed launch policy these entities feed.