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 agentRoles 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,coder2orvalidator2. 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: bindcoder1itself, because acoderbinding orAISQUARE_BIN_CODERdoes 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 roleThe 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 ~/.claude2A 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.
| Flag | Effect |
|---|---|
--bin CMD | the executable this role launches (a second install, a wrapper script) |
--env KEY=VALUE | repeatable; merges per key with what is already bound |
--env-file KEY=PATH | repeatable; sets the variable to the file's text at every launch, never printed. For a secret: see A reviewer that cannot push |
--arg ARG | repeatable; appends to the role's standing arguments |
--unset KEY | remove one env key or env file, applied after the merge |
--account ACCOUNT | the Claude account this role launches under; see How a launch picks an account |
--clear-account | remove the role's account, keep the rest |
--clear | remove 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
| Command | Carries |
|---|---|
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:
| Order | Source | Shown as |
|---|---|---|
| 1 | --command on launch, --bin on spawn | flag |
| 2 | AISQUARE_BIN_<ROLE> | env |
| 3 | AISQUARE_AGENT_BIN | env:global |
| 4 | the role's bound bin | config |
| 5 | claude | default |
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 bindingFusing 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 harnessbase 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 nowPresence 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.
Control the fleet remotely
Two ways to reach your agents away from the desk. rlx's own Remote puts the whole fleet on your phone through your ngrok tunnel; Claude Code's Remote Control, turned on per role, lets you continue one agent's session from claude.ai/code or the Claude app.
Your fleet on your phone
Step away from the desk and keep your rlx fleet moving. See what needs you across every project, watch any agent live, and answer it from your phone, through your own tunnel and read-only until you allow more.