> ## Documentation Index
> Fetch the complete documentation index at: https://starforge.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# sf admin

> Administrator commands: users, quotas, and maintenance mode

Requires the admin role. See the [Admin page](/en/console/admin) for the corresponding console features.

## User Management

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin users                          # All users
sf admin user-add <username>            # Create a local account (password entered interactively)
sf admin set-role <username> <role>     # admin / operator
sf admin disable <username> --on        # Disable
sf admin disable <username> --off       # Enable
```

## Quotas

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin set-quota <username> \
  --gpus 16 \                  # Concurrent GPU limit (default 8)
  --jobs 6 \                   # Concurrent job limit (default 4)
  --daily-gpu-hours 200 \      # Daily GPU-hours (0 = unlimited)
  --max-storage-gb 2000 \      # Run-directory storage cap in GiB (0 = unlimited)
  --profiles h200,h100 \       # Allowed profiles (comma-separated, empty = all)
  --priority 10                # Queue priority (default 0)
```

<Note>
  Storage quotas do not work like GPU quotas. GPUs are **reserved**: submitting a
  job sets its cards aside up front. Storage can only be **measured after the
  fact** — a training process writes to disk without telling the platform, and a
  job cannot say how much it will write, so there is nothing to reserve. The rule
  is "already over means no new jobs are dequeued"; running jobs are unaffected.

  Usage comes from a periodic background scan
  (`FORGE_STORAGE_SCAN_INTERVAL_S`, 600s by default), so it is eventually
  consistent and a user may briefly exceed the cap between scans. If the scan
  wedges, the gate admits rather than refusing — better to show "stale" on the
  dashboard than to stop everyone from submitting.
</Note>

## Maintenance Mode

Drain the cluster → upgrade → resume; jobs resume training from checkpoints without losing progress:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin maintenance status     # Current status and whether the cluster can be safely restarted
sf admin maintenance drain      # Enter maintenance mode and drain (idempotent; run again if not fully drained)
# …… upgrade the cluster / platform ……
sf admin maintenance resume     # Exit maintenance; paused jobs resume training automatically
```

<Note>
  Maintenance mode is the master switch: after drain, new jobs are not dequeued and running jobs are paused (checkpoints kept). After resume everything recovers automatically, with no per-job operations needed.
</Note>

## `sf admin`

Manage users and quotas

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin <subcommand>
```

| Command                | Description                            |
| ---------------------- | -------------------------------------- |
| `sf admin disable`     | Disable or enable a user               |
| `sf admin maintenance` | Drain, upgrade and resume the cluster  |
| `sf admin set-quota`   | Set a user's compute and storage quota |
| `sf admin set-role`    | Change a user's role                   |
| `sf admin user-add`    | Create a local account                 |
| `sf admin users`       | List every user                        |

### `sf admin disable`

Disable or enable a user

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin disable <USERNAME> [options]
```

| Argument   | Description  |
| ---------- | ------------ |
| `USERNAME` | **required** |

| Option | Description                  |
| ------ | ---------------------------- |
| `--on` | --on disables, --off enables |

### `sf admin maintenance`

Drain, upgrade and resume the cluster

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin maintenance <subcommand>
```

| Command                       | Description                       |
| ----------------------------- | --------------------------------- |
| `sf admin maintenance drain`  | Enter maintenance mode and drain  |
| `sf admin maintenance resume` | Leave maintenance mode            |
| `sf admin maintenance status` | Show maintenance state and safety |

#### `sf admin maintenance drain`

Enter maintenance mode and drain

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin maintenance drain [options]
```

| Option   | Description                                                         |
| -------- | ------------------------------------------------------------------- |
| `--note` | Maintenance note, echoed back to anyone whose submission is blocked |

#### `sf admin maintenance resume`

Leave maintenance mode

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin maintenance resume
```

No options beyond `--help`.

#### `sf admin maintenance status`

Show maintenance state and safety

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin maintenance status
```

No options beyond `--help`.

### `sf admin set-quota`

Set a user's compute and storage quota

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin set-quota <USERNAME> [options]
```

| Argument   | Description  |
| ---------- | ------------ |
| `USERNAME` | **required** |

| Option                      | Description                                                                                                                                                 |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--gpus` `<int>`            | Concurrent GPU cap (default `8`)                                                                                                                            |
| `--jobs` `<int>`            | Concurrent job cap (default `4`)                                                                                                                            |
| `--daily-gpu-hours` `<int>` | GPU-hours per day (0 = unlimited) (default `0`)                                                                                                             |
| `--max-storage-gb` `<int>`  | Cap on the user's run directories in GiB (0 = unlimited). Enforced against a periodic scan: going over blocks new jobs, running ones continue (default `0`) |
| `--profiles`                | Allowed profiles (comma separated, empty = all)                                                                                                             |
| `--priority` `<int>`        | Queue priority (default `0`)                                                                                                                                |

### `sf admin set-role`

Change a user's role

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin set-role <USERNAME> <ROLE>
```

| Argument   | Description  |
| ---------- | ------------ |
| `USERNAME` | **required** |
| `ROLE`     | **required** |

No options beyond `--help`.

### `sf admin user-add`

Create a local account

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin user-add <USERNAME> [options]
```

| Argument   | Description  |
| ---------- | ------------ |
| `USERNAME` | **required** |

| Option             | Description                                      |
| ------------------ | ------------------------------------------------ |
| `--password`, `-p` | **required**                                     |
| `--role`           | admin \| operator \| viewer (default `operator`) |
| `--email`          | —                                                |

### `sf admin users`

List every user

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin users
```

No options beyond `--help`.