ts runner

List the registered runners — the execution-side processes that carry workloads for an account — and deregister one.

Usage

ts runners
ts runner <id>
ts runner delete <id> [--force]

Description

A runner is the process that executes work on a machine and holds a tunnel back to the server. It registers itself once, then appears here until it is deregistered.

ts runners lists the runners registered to the account you are signed in as: the runner id, its display name and hostname, its platform and architecture, whether the tunnel is currently up, its status, and when it was last seen. ONLINE is the live answer — whether the server has a connection to it this second — while LAST SEEN is the persisted timestamp and is the useful column when the answer is no.

ts runner <id> prints one runner's status as JSON. This endpoint is reserved for service callers, so a normal administrator login is refused: run it with --local on the server itself, or read the same fields out of the ts runners row. The two commands want opposite credentials: ts runners needs a signed-in account, because the list is that account's runners, while ts runner <id> needs the service credential. Expect to pass --local to one and not the other.

ts runner delete deregisters a runner permanently. If the runner is connected, the server tells it that it has been revoked and the runner process shuts itself down, taking whatever it was executing with it. The runner's session rows are then removed and the registration is deleted, so the runner disappears from ts runners and its stored session history goes with it. An offline runner is deleted just as thoroughly; it simply finds its credentials rejected the next time it tries to connect. Getting the runner back means registering it again from scratch, so the command prompts unless you pass --force.

You can only delete a runner registered to your own account. This is the command formerly spelled ts agent / ts agents; those names are not registered as aliases, so use runner and runners.

Options

Flag	Description	Default/Values	Notes
--force, -f	Deregister without confirming.		delete only.
--local	Target the install on this machine with a service token.		The only way ts runner <id> succeeds; ts runners rejects it, since a service token owns no runners.

Examples

# What is registered, and what is actually connected?
ts runners

# Full hostnames and ids, untruncated
ts runners --no-trunc

# One runner's status, from the server itself
ts runner --local build02-9f3ac21d

# Deregister a runner you are retiring
ts runner delete build02-9f3ac21d --force

# Gotcha: this is not "restart the runner". Deleting one kills the connected
# process, drops its session history, and requires a fresh registration to
# undo. Check the ONLINE column and what it is running before you do it.

Exit Codes

0 on success. -1 when no runner id is given. -4 when no account is signed in, and also on ts runner <id> with an ordinary login, because that endpoint requires a service credential. -5 when the runner belongs to another account. -6 when no runner has that id. 9009 if you reach for the old ts agents spelling, which is not a registered command.

Related Commands

• ts sessions — The sessions a runner is carrying; ts session <id> names the runner it is on.
• ts user — The account a runner is registered to, which is the account that may delete it.