# Use cartridges and run programs

A bay number identifies a physical slot, from `01` through `12`. It stays tied
to the slot rather than the order in which Linux discovers USB disks.

| Cartridge | Role |
| --- | --- |
| SYSTEM | Supplies the read-only operating system used at boot |
| PROGRAM | Supplies applications and their runtime dependencies |
| DATA | Stores your writable files at `/data` |
| ENVIRONMENT | Requests an installed desktop profile, such as WindowMaker |

## Inspect a bay

Insert the cartridge, then run:

```sh
fds bays
fds bay 01
```

USB discovery takes place asynchronously. `fds bay` shows its state, identity,
mount location, running process count and software catalogue. `fds --json bay 01`
returns structured details, including command aliases. `fds rescan` refreshes
the inventory. No application starts merely because a PROGRAM cartridge is inserted.

| State | Meaning and next action |
| --- | --- |
| EMPTY | No cartridge is detected |
| MOUNTED READ ONLY | Contents are available; PROGRAM commands can run |
| MOUNTED READ WRITE | DATA is active at `/data` |
| SAFE | Storage is released; remove the cartridge |
| PROTECTED | This cartridge supplies the running SYSTEM; shut down before removal |
| UNCONFIGURED | The physical slot needs a bay mapping |
| ERROR / AMBIGUOUS | Read the detail; correct the media or mapping before use |

## Run a software command

For the included hello/report cartridge:

```sh
hello 'Hello from my cartridge'
report
fds run 01 -- demo.hello:hello 'Hello from my cartridge'
```

Direct commands run in the foreground with your terminal, input/output streams,
arguments, working directory and exit code. Pipes and redirection work normally.
`fds run` starts a managed background program and prints its PID; its output is
written to `/run/log/cartridged/current`. Both forms run as the ordinary FDS user
and are tracked for cartridge removal.

New cartridges run directly from read-only payload partitions. They require no
program extraction or compilation on FDS. The stable `/run/fds/bin` directory is
already in the console and terminal PATH, so existing shells see inserted commands.

If cartridges export the same command name, the lowest numbered bay wins.
Within a bay, the first software selector in lexical order wins. System commands
appear earlier in PATH and retain their usual meanings. To select a specific
cartridge command, use its qualified alias:

```sh
b01:demo.hello:hello 'Explicit bay and software'
fds run 01 -- demo.hello:hello
```

Legacy PROGRAM media uses `b01:COMMAND` for a qualified direct alias. Commands
are removed on eject/unplug; a shared name falls back to the next available bay.
After the final cartridge is removed, a shell may remember the old executable
path; `hash -r` clears Bash's command cache.

## Eject safely

```sh
cd "$HOME"
fds eject 01
fds bay 01
```

Eject stops managed programs, flushes writable storage and releases its mounts.
Remove the cartridge after **SAFE** is reported. If eject fails, close files,
shells or extra mounts using that cartridge and retry. Never treat a timeout as
permission to pull writable media. Use `fds poweroff` to stop the whole computer;
swap the running SYSTEM only after shutdown.

The [control panel](desktop.md) provides the same safe-eject action. For writable
storage behavior, see [DATA and files](data.md).

## Configure physical bay numbering

Run `fds topology` with one identifiable USB device inserted in each slot in
turn. Record the controller/hub topology for both USB 2 and USB 3 connections,
then map those stable identities in the machine's `bays.toml`. Do not map
`/dev/sda` names or enumeration order. The emulator supplies its own known map.

Use [machine settings](internal-storage.md) to validate, export and install the
configuration. The detailed wiring/calibration procedure is in the
[hardware engineering reference](developer/cartridges.md).