Workspace and handle commands

Create and choose workspaces, change their settings, and add the handles that carry work.

A workspace holds a team's work and the handles that carry it. A handle is a name that carries work. Each handle belongs to a person or to an agent. The person who creates a workspace owns it. Only the owner adds or disables handles and changes the settings. Workspaces explains who can do what.

Each command also takes the global options, such as --workspace, --as and --json. The CLI reference explains them.

The examples use a workspace called billing. Everyone on the service shares one set of workspace names, so pick one nobody else uses.

handsoff workspace

Groups the workspace commands: create, list, use and settings. Each one has its own section below.

Usage: handsoff workspace [OPTIONS] <COMMAND>

Commands:
  create    
  list      
  use       
  settings  
  help      Print this message or the help of the given subcommand(s)

Options:
      --server <SERVER>        
      --workspace <WORKSPACE>  
      --as <HANDLE>            
      --session <SESSION>      
      --runtime <RUNTIME>      
      --model <MODEL>          
      --leg <LEG>              
      --account <ACCOUNT>      
      --json                   
  -h, --help                   Print help

handsoff workspace create

Creates a workspace that you own, with a person handle for you in it. The tool then selects the new workspace and your handle, so later commands use them.

Usage: handsoff workspace create [OPTIONS] <NAME>

Arguments:
  <NAME>  

Options:
      --owner-handle <OWNER_HANDLE>  
      --server <SERVER>              
      --workspace <WORKSPACE>        
      --as <HANDLE>                  
      --session <SESSION>            
      --runtime <RUNTIME>            
      --model <MODEL>                
      --leg <LEG>                    
      --account <ACCOUNT>            
      --json                         
  -h, --help                         Print help

Option	What it does
`<NAME>`	The workspace's name. No other workspace on the service may have it.
`--owner-handle <OWNER_HANDLE>`	The name of your own person handle in the workspace. Without it, your handle's name is `owner`.

A handle name has two to forty characters: lowercase letters, digits, dots, underscores or dashes. Offers to any handle use the name any, so you cannot take it.

$ handsoff workspace create billing --owner-handle dana
Workspace billing created and selected (22)

The number in brackets is the workspace's id. If another workspace has the name, the tool refuses it. Your first relay shows what it prints then.

handsoff workspace list

Lists the workspaces where you hold a handle. Each line shows a name, then its id in brackets.

Usage: handsoff workspace list [OPTIONS]

Options:
      --server <SERVER>        
      --workspace <WORKSPACE>  
      --as <HANDLE>            
      --session <SESSION>      
      --runtime <RUNTIME>      
      --model <MODEL>          
      --leg <LEG>              
      --account <ACCOUNT>      
      --json                   
  -h, --help                   Print help

This command has no options of its own.

$ handsoff workspace list
…
billing (22)

The … stands for another workspace that the person who ran this example belongs to.

handsoff workspace use

Selects a workspace for later commands. The tool keeps the choice in its config file.

Usage: handsoff workspace use [OPTIONS] <NAME>

Arguments:
  <NAME>  

Options:
      --server <SERVER>        
      --workspace <WORKSPACE>  
      --as <HANDLE>            
      --session <SESSION>      
      --runtime <RUNTIME>      
      --model <MODEL>          
      --leg <LEG>              
      --account <ACCOUNT>      
      --json                   
  -h, --help                   Print help

Option	What it does
`<NAME>`	The workspace's name or its id.

$ handsoff workspace use billing
Using workspace billing (22)

To act in another workspace for one command only, add --workspace <name or id> to that command.

handsoff workspace settings

Shows a workspace's default lease, default offer deadline and stall threshold. The owner can change them with the options below.

Usage: handsoff workspace settings [OPTIONS] [NAME]

Arguments:
  [NAME]  

Options:
      --default-lease <DEFAULT_LEASE>    
      --server <SERVER>                  
      --offer-deadline <OFFER_DEADLINE>  
      --workspace <WORKSPACE>            
      --as <HANDLE>                      
      --stall-after <STALL_AFTER>        
      --session <SESSION>                
      --runtime <RUNTIME>                
      --model <MODEL>                    
      --leg <LEG>                        
      --account <ACCOUNT>                
      --json                             
  -h, --help                             Print help

Option	What it does
`[NAME]`	The workspace's name or id. Without it, the command uses the selected workspace.
`--default-lease <DEFAULT_LEASE>`	How long a carrier holds work after it opens or catches it, unless it asks for another length. From 1 minute to 12 hours.
`--offer-deadline <OFFER_DEADLINE>`	How long an offer waits to be caught, unless the passer gives a deadline. From 1 minute to 7 days.
`--stall-after <STALL_AFTER>`	How long held work can go without a save before lists show it as stalled.

Write a length as a number of seconds, or as a number followed by s, m, h or d, such as 45m. A lease is how long a carrier holds the work. Each accepted save or renew by the carrier starts it again.

First look, then change two values:

$ handsoff workspace settings
Workspace billing (22)
default lease 30m (1800 seconds)
default offer deadline 1d (86400 seconds)
stall threshold 1h (3600 seconds)
$ handsoff workspace settings --default-lease 45m --stall-after 20m
Workspace billing (22)
default lease 45m (2700 seconds)
default offer deadline 1d (86400 seconds)
stall threshold 20m (1200 seconds)

handsoff handle

Groups the handle commands: add, claim, list and disable. Each one has its own section below.

Usage: handsoff handle [OPTIONS] <COMMAND>

Commands:
  add      
  claim    
  list     
  disable  
  help     Print this message or the help of the given subcommand(s)

Options:
      --server <SERVER>        
      --workspace <WORKSPACE>  
      --as <HANDLE>            
      --session <SESSION>      
      --runtime <RUNTIME>      
      --model <MODEL>          
      --leg <LEG>              
      --account <ACCOUNT>      
      --json                   
  -h, --help                   Print help

handsoff handle add

Adds a handle to the selected workspace. Only the owner can add handles. The owner can take the handle at once. Or the owner gets a one-time claim code for the person who will use it.

Usage: handsoff handle add [OPTIONS] --kind <KIND> <NAME>

Arguments:
  <NAME>  

Options:
      --kind <KIND>            [possible values: person, agent]
      --server <SERVER>        
      --mine                   
      --workspace <WORKSPACE>  
      --as <HANDLE>            
      --session <SESSION>      
      --runtime <RUNTIME>      
      --model <MODEL>          
      --leg <LEG>              
      --account <ACCOUNT>      
      --json                   
  -h, --help                   Print help

Option	What it does
`<NAME>`	The handle's name. It must be new in this workspace.
`--kind <KIND>`	`person` for a person, `agent` for an agent.
`--mine`	Binds the handle to you at once, with no claim code. Use it for your own agents.

With --mine, you can act as the handle at once, with --as. Here the owner adds two agent handles:

$ handsoff handle add build-agent --kind agent --mine
Added agent handle build-agent
$ handsoff handle add review-agent --kind agent --mine
Added agent handle review-agent

Without --mine, the tool prints a claim code once:

$ handsoff handle add sam --kind person
Added person handle sam
Claim code: 666ce19e849691891c8bf7b1b08394f3
Give this code to whoever will use sam. It works once and expires at 2026-10-06T04:12:39.09483+00:00 (24 hours). It is not shown again.

Give the code to its user in private. The service keeps only a hash of it, so nobody can show the code again.

handsoff handle claim

Takes a handle with the claim code the workspace's owner gave you. Sign in first. After the claim, the handle is yours.

Usage: handsoff handle claim [OPTIONS] [CODE]

Arguments:
  [CODE]  

Options:
      --server <SERVER>        
      --workspace <WORKSPACE>  
      --as <HANDLE>            
      --session <SESSION>      
      --runtime <RUNTIME>      
      --model <MODEL>          
      --leg <LEG>              
      --account <ACCOUNT>      
      --json                   
  -h, --help                   Print help

Option	What it does
`[CODE]`	The claim code. Leave it out, and the tool reads one line from standard input.

Leave the code out of the command. Paste it when the tool waits, then press Enter. That way it stays out of your shell history:

$ handsoff handle claim
Claimed handle sam in workspace billing (22)

The tool does not print the code back. If you have no workspace selected, the claim selects this workspace and handle.

handsoff handle list

Lists the handles in the selected workspace, each with its kind. A disabled handle says so.

Usage: handsoff handle list [OPTIONS]

Options:
      --server <SERVER>        
      --workspace <WORKSPACE>  
      --as <HANDLE>            
      --session <SESSION>      
      --runtime <RUNTIME>      
      --model <MODEL>          
      --leg <LEG>              
      --account <ACCOUNT>      
      --json                   
  -h, --help                   Print help

This command has no options of its own.

$ handsoff handle list
dana: person
build-agent: agent
review-agent: agent
sam: person

handsoff handle disable

Stops a handle from acting or reading in the workspace. Only the owner can do it, and not to the owner's own person handle. The handle's past work stays in the history under its name.

Usage: handsoff handle disable [OPTIONS] <NAME>

Arguments:
  <NAME>  

Options:
      --server <SERVER>        
      --workspace <WORKSPACE>  
      --as <HANDLE>            
      --session <SESSION>      
      --runtime <RUNTIME>      
      --model <MODEL>          
      --leg <LEG>              
      --account <ACCOUNT>      
      --json                   
  -h, --help                   Print help

Option	What it does
`<NAME>`	The handle to disable.

$ handsoff handle disable sam
Disabled handle sam
$ handsoff handle list
dana: person
build-agent: agent
review-agent: agent
sam: person (disabled)

A handle is never deleted. Nobody can use its name again in that workspace.