> ## Documentation Index
> Fetch the complete documentation index at: https://docs.internal.nscale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> How the Fleet Manager codebase is organised and where to start as a developer.

Fleet Manager is a Python 3.12 codebase built around a typed API layer, a [Temporal](../start-here/glossary#temporal)-based
workflow engine, background agents, and supporting CLIs for deployment and operations.

## Developer Onboarding

Before working in the codebase, you'll typically need:

* **Repository access** to `nscaledev/fleet-manager`
* **[1Password](../start-here/glossary#1password)** access to the Fleet Manager vaults (see [Getting Access](../start-here/getting-access))
* **Teleport** access to the management environment for any work against shared dev infrastructure

Raise access requests in the `#fleet-manager-chat` Slack channel.

### Local Setup

Clone the repository and set up the local environment from the repo root:

```bash theme={null}
make dev
```

After setup, the CLI is available as:

```bash theme={null}
uv run fleetctl --help
```

### Teleport and Management Network

Most development work assumes access to the management network. For the shared dev
environment, engineers typically work from management VMs such as `app51`.

Authenticate with Teleport first:

```bash theme={null}
tsh login
```

Then connect to the target VM with the login shown in the Teleport profile output:

```bash theme={null}
tsh ssh <teleport-login>@app51
```

If you need regular SSH access to Teleport hosts, configure it:

```bash theme={null}
tsh config >> ~/.ssh/config
```

### Runtime Configuration

Fleet Manager expects explicit environment configuration:

* `ENVIRONMENT` selects the runtime environment (`local`, `dev`, `stg`, `uat`, `prod`)
* `OP_VAULT_SELECTOR` selects the target Fleet Manager vault (for example `hub`, `sta1`, `glo1`)
* `API_DEBUG` defaults to `false`; set `API_DEBUG=true` only for local Django debug pages

Local development runtimes still map to the `dev` vault for credentials while keeping
separate local runtime behaviour.

## How To Read The Developer Docs

* Read [Architecture](./architecture) first if you need the system model
* Use [Device State Machines](./device-state-machines) for all [device](../start-here/glossary#node) status axes, conditions, and integration write paths
* Use [Workflow State Transitions](./workflow-state-transitions) for the map from current workflows to device state and eligibility gates
* Use [Add a New Workflow](./authoring-guides/build-a-new-workflow) when extending the workflow platform
* Use [Integrate with the API](./integrate-with-the-api/overview) for client authentication, scopes, and consumer integration
* Use [Build a New Agent](./authoring-guides/build-a-new-agent) and
  [Build a New Burn-in Test](./authoring-guides/build-a-new-burn-in-test) for extension points
  beyond workflow authoring

## Important Agent Skills

Shared agent skills live under `.agents/skills/`. Ask the coding agent to use a skill by name when you
want its workflow applied explicitly; mandatory skills also activate from the files and systems being
changed.

| Skill | Use it when |
| - | - |
| `fm-review` | Default is `design` while shaping non-trivial code; say `gate` / `pre-PR` / `finish-up` before opening a PR. |
| `sentinel` | Investigating production with read-only logs, traces, metrics, Kubernetes state, or Fleet Manager API evidence. |
| `e2e-tests` | Debugging or verifying a branch/PR through Docker Compose or live infrastructure; it selects the safe environment and runs the focused test loop. |
| `temporal-workflows` | **Required** when authoring or changing workflows, activities, workers, registry entries, or failure taxonomy. |
| `agent-machinery` | **Required** for inbound integration agents under `src/fleet_manager/agents/`. |
| `bmc-redfish` | **Required** for [BMC](../start-here/glossary#bmc), [Redfish](../start-here/glossary#redfish), [IPMI](../start-here/glossary#ipmi), vendor, enrolment, or BMC-facing activity work. |
| `burn-in-test-creator` | Adding a hardware [burn-in](../start-here/glossary#burn-in) test and covering every registry, policy, runner, and verification touchpoint. |
| `sop-diagnostics` | Following an existing SOP/runbook for a known host, job, [Ironic](../start-here/glossary#ironic), or CHAD failure. |
| `tracing` | **Required** for API, agent, [NATS](../start-here/glossary#nats), Temporal-worker, tracing, or metrics instrumentation changes. |
| `temporal-slurm` | Local burn-in test development on a real [SLURM](../start-here/glossary#slurm) [cluster](../start-here/glossary#cluster) — start a namespaced worker, dispatch single-/multi-node tests, calibrate, and triage failures. |

## Contributing to the Docs

The published docs are sourced from this repository. If you find drift, gaps, or stale
instructions:

* Open a pull request against `nscaledev/fleet-manager`
* Update the relevant source doc under `docs/` or `docs/published/`
* Keep deployment runbooks and published pages aligned when behaviour changes

## Current Focus

The published developer guide currently emphasises:

* Overall architecture and dependency boundaries
* Hub/satellite deployment architecture
* Workflow authoring

API integration, agent authoring, and hardware-test authoring pages exist as placeholders and
will be populated as the source material is split out of the repo's internal docs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.