Settings

Settings come from environment variables with the MCARDUPILOT_ prefix, or from a .env file in the working directory. The server and the library read the same ones: a Sitl in a script leases from the same pool and lock directory as the server unless you pass it other Settings.

Environment variable	Type	Default	What it does
MCARDUPILOT_ARDUPILOT	Path	~/ardupilot	ArduPilot tree; read and run only, never built or edited
MCARDUPILOT_BINARY	Path | None	<ardupilot>/build/sitl/bin/arduplane	SITL binary; default <ardupilot>/build/sitl/bin/arduplane
MCARDUPILOT_DATA_DIR	Path	~/.local/share/mcardupilot	lease locks, session run directories, kept logs
MCARDUPILOT_INSTANCE_POOL	str (a pool spec)	40-59	instances this server may lease, "40-59" or "40,41,45-47"
MCARDUPILOT_WAIT_CAP_S	float	85	longest any waiting tool blocks
MCARDUPILOT_SESSION_IDLE_S	float	1800	close a session idle this long
MCARDUPILOT_REAP_INTERVAL_S	float	30	how often idle sessions are checked
MCARDUPILOT_STALL_S	float	30	a session's SITL whose clock stops this long is dead
MCARDUPILOT_LOG_BUDGET_GB	float	20	kept dataflash logs prune past this
MCARDUPILOT_BUILD_TREES	list[Path]	[]	trees build_sitl may build, separated by : or , (a patched tree goes here)
MCARDUPILOT_BUILD_PYTHON	Path | None	None	Python with ArduPilot's build packages (empy 3.3.4 and the rest); default ~/venv-ardupilot if it exists, else python3 on PATH outside this server's venv
MCARDUPILOT_BUILD_DEFAULT_TREE	bool	True	also build the ardupilot tree while its checkout is clean
MCARDUPILOT_VIDEO_HOST	str	127.0.0.1	where live feeds listen; 0.0.0.0 for the LAN
MCARDUPILOT_VIDEO_PORT_BASE	int	8400	a session's live feed is on this plus its instance
MCARDUPILOT_VIDEO_SIZE	str	960x540
MCARDUPILOT_VIDEO_FPS	float	30
MCARDUPILOT_VIDEO_ENCODER	"auto" | "h264_nvenc" | "libx264"	auto
MCARDUPILOT_VIDEO_FGVIEW	bool	True	launch SITL with --enable-fgview, so live feeds get its pose
MCARDUPILOT_TRANSPORT	"stdio" | "http"	stdio	stdio for one client; http serves streamable HTTP for a shared deployment
MCARDUPILOT_HTTP_HOST	str	127.0.0.1	address the http transport binds
MCARDUPILOT_HTTP_PORT	int	8374	port the http transport listens on

The instance pool

MCARDUPILOT_INSTANCE_POOL takes a range, a list, or both: "40-59", "40,41,45-47". Instances are leased in the order written. The validator refuses three numbers outright:

Instance	Why
0	autotest.py always uses it, and takes no lease
14, 15	their MAVLink ports, 5900 and 5910, sit in the range VNC servers use (5900 and up), which is a common clash on a workstation running remote desktops

It also refuses duplicates and numbers so high that SITL’s ports would pass 65535.

Every server and script sharing a machine should share MCARDUPILOT_DATA_DIR, since that is where the lease locks live. Pools may differ between them: list_instances reads every lock file in the directory, in the pool or not.

Directories under the data directory

Path	Holds
leases/instance-<n>.lock	the flock lease files, one per instance ever leased
sessions/<n>/	a session’s SITL run directory: parameter files, scripts/, sitl.log, sitl.pid, and the live logs/
logs/	kept dataflash logs, held to MCARDUPILOT_LOG_BUDGET_GB, with <name>.BIN.pin beside any pinned one
run/<n>/	the library’s default run root for a Sitl started outside the server

HTTP is a seam, not a deployment

MCARDUPILOT_TRANSPORT=http serves the same tools as stateless streamable HTTP with JSON responses, and restricts log paths to the data directory. It has no authentication of its own. Keep it on 127.0.0.1, or put it behind something that authenticates.