AISquare
rlx

Launching sessions

Start a seat with rlx launch, and pin what it launches: binary, environment, extra arguments and account, bound once per role.

The fleet starts its agents for you. To run a role yourself, one terminal each (see Running a team by hand), rlx launch is the way in. It does what putting AISQUARE_ROLE in front of claude does, and adds three things worth having: it checks the role name, it opts this repo in to the board explicitly, and it carries whatever you have pinned to that role. The fleet's own spawns launch through it too, so a role's binding reaches them as well.

rlx launch coder                 # like AISQUARE_ROLE=coder claude
rlx launch coder --model opus    # anything after the role goes to the agent

Roles and numbered seats

A launch takes one of the roles listed in Running a team by hand, or agent for a plain session with no role. Two other shapes are accepted:

  • A numbered seat of one of those roles, like coder1, coder2 or validator2. Crews run several agents in one role and need to tell them apart on the board. The seat is briefed with its role's work cycle and walks its role's model ladder, so the number is an identity, not a new role. Its launch spec is its own, though: bind coder1 itself, because a coder binding or AISQUARE_BIN_CODER does not reach it.
  • Any role you have bound with rlx team bind. Writing a role into your config is you saying it exists. It has no work cycle and no model ladder of its own.
rlx launch coder2        # a numbered seat
rlx launch docs-writer   # a role you have bound
rlx launch codr          # refused: unknown role

The whitelist stays a whitelist because it catches typos. A mistyped role used to produce a session quietly attached to nothing, which is the footgun it exists to stop.

Pin what a role launches

Parallel agent installs are usually reached through a shell alias:

alias claude2='CLAUDE_CONFIG_DIR="$HOME/.claude2" CLAUDE_CODE_TMPDIR="$HOME/.cache/claude2" command claude'

An alias is not an executable, so no amount of pointing rlx at claude2 will ever find it. The alias is really two environment variables wrapped around the ordinary binary, so that is what you bind:

rlx team bind coder1 \
  --env CLAUDE_CONFIG_DIR='$HOME/.claude2' \
  --env CLAUDE_CODE_TMPDIR='$HOME/.cache/claude2'

Every later rlx launch coder1 and rlx team spawn coder1 carries that with no flag. A binding on a fleet role, such as reviewer, reaches that role's fleet spawn, restart and switch too.

rlx's hooks are installed per Claude Code config directory, and they are how a session reaches the board. If the directory you bound has never had them, connect it once:

rlx agents connect claude-code --config-dir ~/.claude2

A plain rlx agents connect claude-code targets $CLAUDE_CONFIG_DIR or ~/.claude, not the directory you bound, and rlx launch does not check. Without this step the seat starts but never shows on the board.

Quote values that contain $

Single quotes keep $HOME intact so your shell does not expand it before rlx stores it. Expansion happens at launch, which is what lets one binding follow you to a machine with a different home directory. An undefined variable is left verbatim rather than blanked, deliberately: a silently empty CLAUDE_CONFIG_DIR starts a fresh unauthenticated profile, and that surfaces as a login failure hours later instead of as the typo it is.

Bindings live in ~/.aisquare/config.toml:

[team.profiles.coder1]
bin = "claude"
args = ["--model", "opus"]

[team.profiles.coder1.env]
CLAUDE_CONFIG_DIR = "$HOME/.claude2"
CLAUDE_CODE_TMPDIR = "$HOME/.cache/claude2"

A variable bound with --env-file sits under [team.profiles.<role>.env_files] as a path, and --account as the profile's account.

FlagEffect
--bin CMDthe executable this role launches (a second install, a wrapper script)
--env KEY=VALUErepeatable; merges per key with what is already bound
--env-file KEY=PATHrepeatable; sets the variable to the file's text at every launch, never printed. For a secret: see A reviewer that cannot push
--arg ARGrepeatable; appends to the role's standing arguments
--unset KEYremove one env key or env file, applied after the merge
--account ACCOUNTthe Claude account this role launches under; see How a launch picks an account
--clear-accountremove the role's account, keep the rest
--clearremove this role's binding entirely

rlx team bind with no role at all prints every binding, with values as you wrote them ($HOME unexpanded). ⚙ Settings ▸ App settings ▸ Agent settings ▸ Advanced ▸ Role bindings lists and edits the same bindings.

Environment merges per key and arguments append, so a second bind adds to a role instead of replacing it and you can change one variable without restating its siblings. --unset is applied after the merge.

rlx expands ~ and $VAR in environment values and env-file paths, because those are universal, and otherwise carries what you bind as written (--bin too, so give it a name on your PATH or a full path). It never infers a path and never invents a second variable from the first. That ignorance is the point. Parallel installs, wrapper scripts, proxies and regions all work the same way, without the tool knowing what any of your variables mean. The two exceptions are checked when you bind, so a typo fails there and not at every later launch: --account names an account rlx manages, and wins over a CLAUDE_CONFIG_DIR in --env; --env-file reads its file once on the spot. rlx doctor's role bindings row warns when a bound CLAUDE_CONFIG_DIR is not a directory or has no rlx hooks, or a bound CLAUDE_CODE_TMPDIR cannot be written, and prints the fix.

Two roles may bind the same values. Sharing one install across several seats is a supported setup and nothing warns about it.

What each command carries

CommandCarries
rlx launch <role>the whole binding: binary, environment, extra arguments and account; then replaces itself with the agent
rlx team spawn <role>the binding's binary, environment and extra arguments, plus a model and effort from the role's ladder; prints the command by default, --exec runs it

team spawn applies no account at all, whether bound, a project default or the machine default: it runs on whatever CLAUDE_CONFIG_DIR your shell and the binding's --env give it. So on a machine with accounts signed in, rlx launch coder and rlx team spawn coder --exec can start on different Claude logins. Both accept --env KEY=VALUE (repeatable) to override a single run without touching config. For one run's binary, launch takes --command and spawn takes --bin. Extra arguments go after the role on launch, and in --arg on spawn.

Which binary a role runs

rlx launch and team spawn resolve the binary down the same ladder:

OrderSourceShown as
1--command on launch, --bin on spawnflag
2AISQUARE_BIN_<ROLE>env
3AISQUARE_AGENT_BINenv:global
4the role's bound binconfig
5claudedefault

Role names in AISQUARE_BIN_<ROLE> are upper-cased, and anything that is not a letter or digit becomes an underscore, so code-reviewer reads AISQUARE_BIN_CODE_REVIEWER.

Resolution never touches the filesystem. It answers "what was asked for", and the launch reports "it is not there" separately, naming the rung that chose it:

✗ 'claude' is not on your PATH (chosen by: default) — install it, pass --command, or change the role's binding

Fusing the two would let a typo fall back to the default install and run the wrong agent under the right role name, which is worse than not launching at all.

See what a role resolves to

rlx team harness
base effort: high (default)
planner    fable→opus→sonnet    effort=high      ( 0) → fable [optimistic]
coder      sonnet→opus          effort=high      ( 0) → sonnet [optimistic]  env=CLAUDE_CODE_TMPDIR,CLAUDE_CONFIG_DIR
runner     sonnet→opus          effort=high      ( 0) → sonnet [optimistic]
validator  fable→opus           effort=xhigh     (+1) → fable [optimistic]
manager    fable→opus→sonnet    effort=high      ( 0) → fable [optimistic]
tester     sonnet→opus          effort=high      ( 0) → sonnet [optimistic]
reviewer   sonnet→opus          effort=high      ( 0) → sonnet [optimistic]  bin=claude-readonly [config]
ui-tester  sonnet→opus          effort=high      ( 0) → sonnet [optimistic]  role_args=--chrome
Resolution shown without probing — `rlx team spawn <role>` verifies live.

Here coder is bound with the two variables from Pin what a role launches, and reviewer to a wrapper script on the PATH. Per role: the model ladder and effort, then the binary when it is not the default, tagged with the rung that chose it, the environment keys the role carries, a +Nargs count when it is bound extra arguments, and any flags the role always launches with. Only keys are printed, never values. They are paths and tokens, and this is a terminal. rlx team spawn <role> names each key's source too, in its banner and in its --json.

The matrix lists the eight roles that have a model ladder. A numbered seat walks its role's ladder, so rlx team spawn coder1 picks the coder's model, but the seat's own binding is not in the matrix: rlx team bind lists it, and rlx team spawn coder1 prints the command it would run. A role you define yourself has no ladder and launches on the session default model. The ladder is team spawn's; a fleet spawn picks its model as Models and effort describes.

Ghost sessions

A crashed terminal or a dead loop lingers on the board as (stale). rlx team prune ends those rows so the board shows who is actually here.

rlx team prune --dry-run          # who would be retired, touching nothing
rlx team prune                    # retire them
rlx team prune --older-than 60    # a different silence threshold
rlx team prune --keep ses_abc     # spare one session by id prefix
rlx team prune --release-claims   # also free their in-progress claims now

Presence and claims retire on different clocks. The session row goes at the threshold, 30 minutes by default. Its in-progress claims are freed only if the session has already been silent for four hours when prune runs. A session pruned before then keeps its claims, and a later prune does not come back to it: free them with --release-claims on the prune itself, or afterwards with rlx task release <n>.

The asymmetry is deliberate. For an agent, thirty minutes of silence is usually not idleness, it is one long tool call: a multi-PR review, a build, a fan-out of subagents. Nothing on the board tells that apart from a crashed terminal. Retiring presence early is self-healing, because the session's next heartbeat registers it again. Releasing a claim early is not: a second agent picks up work the first one is still doing, and both push. --release-claims frees claims at the presence threshold instead, for sessions you know are dead.

Either way only presence and orphaned claims change. Tasks, notes and events are left alone. Leases and crashed sessions lists the other ways to free a claim.

On this page