# Launching sessions (/docs/rlx/launching-sessions)

The fleet starts its agents for you. To run a role yourself, one terminal each
(see [Running a team by hand](/docs/rlx/board#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.

```sh
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 [#roles-and-numbered-seats]

A launch takes one of the roles listed in
[Running a team by hand](/docs/rlx/board#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.

```sh
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 [#pin-what-a-role-launches]

Parallel agent installs are usually reached through a shell alias:

```sh
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:

```sh
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:

```sh
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.

<Callout type="warn" title="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.
</Callout>

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

```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](/docs/rlx/fleet#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](/docs/rlx/accounts#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&#x60; 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 [#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 [#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 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 [#see-what-a-role-resolves-to]

```sh
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](#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](/docs/rlx/fleet#models-and-effort) describes.

## Ghost sessions [#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.

```sh
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](/docs/rlx/tasks#leases-and-crashed-sessions)
lists the other ways to free a claim.
