Skip to content

[Docs] Document environment variables and internal-* SLURM configs in the README - #77

Open
aaronsmulktis wants to merge 2 commits into
facebookresearch:mainfrom
aaronsmulktis:aaronsmulktis/readme-env-vars
Open

[Docs] Document environment variables and internal-* SLURM configs in the README#77
aaronsmulktis wants to merge 2 commits into
facebookresearch:mainfrom
aaronsmulktis:aaronsmulktis/readme-env-vars

Conversation

@aaronsmulktis

Copy link
Copy Markdown
Contributor

What

Two new README sections for people cloning the repo to run OpenApps on a cluster, plus one stale-example fix.

Environment variables

  • The .env / load_dotenv() path (both launch_agent.py and launch_parallel_agents.py call it).
  • Table of the vars actually read by configs and code: USER (W&B entity + logs_dir), GPT55_API_KEY, the AWS trio for claude_4_sonnet (client_type: aws), WANDB_API_KEY / WANDB_BASE_URL / WANDB_MODE, EXPERIMENT_CONFIG_PATH, and OPENAPPS_APP / OPENAPPS_MCP_HOST / OPENAPPS_MCP_PORT.
  • How to point an agent's api_key at whatever variable you use, via Hydra interpolation.
  • The env knobs for scripts/conduct.sh (AGENTS, COUNT, MAX_PARALLEL, HEADLESS, LOG_DIR, WANDB_GROUP) and scripts/conduct_slurm.sh (VLLM_MODEL, VLLM_PORT, VLLM_HOST).

Running on SLURM

  • config/mode/slurm_cluster.yaml ships placeholders that sbatch rejects. Documents the existing gitignored internal-* convention: copy it to config/mode/internal-slurm_cluster.yaml, fill in real paths/account/QOS, and select it with mode=internal-slurm_cluster. Includes a placeholder-only example of that file.
  • vLLM host wiring (agent.hostname / agent.port), what conduct_slurm.sh discovery does, and overriding account/QOS/partition at submit time rather than editing the #SBATCH lines.

Drive-by fix: the quickstart used agent=GPT-5-1, which was renamed to the GPT-5.5-* configs — the command as written fails to resolve in Hydra. Now agent=GPT-5.5-computer-use with the matching GPT55_API_KEY. Happy to split this out if preferred.

Test plan

Docs only — no code changes. Claims verified against the repo:

# api_key interpolation override resolves
GPT55_API_KEY=x OPENAI_API_KEY=testkey uv run launch_agent.py \
  agent=GPT-5.5-computer-use 'agent.api_key=${oc.env:OPENAI_API_KEY}' --cfg job --resolve
#   api_key: testkey

# internal-* mode composes
uv run launch_parallel_agents.py mode=internal-slurm_cluster agent=dummy --cfg job
#   cluster: slurm, logs_dir/slurm_account from the untracked file

No cluster paths, hostnames, account names, or QOS names in the added text — placeholders only.

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Sep 1, 2026
… the README

Cloners running OpenApps on a cluster had to read the scripts to find the knobs.
Add two README sections:

- Environment variables: the .env / load_dotenv path, the vars read by configs
  and code (USER, GPT55_API_KEY, AWS_*, WANDB_*, EXPERIMENT_CONFIG_PATH,
  OPENAPPS_MCP_*), how to point an agent's api_key at any env var via Hydra
  interpolation, and the env knobs for scripts/conduct.sh and conduct_slurm.sh.
- Running on SLURM: the gitignored internal-* convention (copy
  config/mode/slurm_cluster.yaml to config/mode/internal-slurm_cluster.yaml and
  select it with mode=internal-slurm_cluster), a placeholder example of that
  file, vLLM host wiring, and submit-time SBATCH overrides.

Also fixes the stale quickstart example: agent=GPT-5-1 no longer exists (renamed
to the GPT-5.5-* configs), so the command as written fails to resolve in Hydra.

Verified: 'agent.api_key=${oc.env:OPENAI_API_KEY}' resolves via --cfg job
--resolve, and mode=internal-slurm_cluster composes.
@aaronsmulktis
aaronsmulktis force-pushed the aaronsmulktis/readme-env-vars branch from dc788e5 to 1c097f5 Compare September 1, 2026 00:38
Adds a commented .env.example covering the variables load_dotenv() actually
feeds into the configs (GPT55_API_KEY / any api_key via Hydra interpolation,
the AWS trio for Bedrock, WANDB_*), so 'cp .env.example .env' is the whole
setup step.

README follow-ups for accuracy:
- point at .env.example instead of an inline heredoc;
- state explicitly that conduct.sh / conduct_slurm.sh and the MCP server read
  their variables from the shell, not from .env -- only launch_agent.py and
  launch_parallel_agents.py call load_dotenv() -- with the 'set -a; source .env'
  idiom for people who want to keep them in one file;
- move OPENAPPS_APP / OPENAPPS_MCP_HOST / OPENAPPS_MCP_PORT into that
  shell-level table, with their defaults and CLI equivalents;
- drop the EXPERIMENT_CONFIG_PATH row: load_config() in configs.py has no
  callers, so documenting it invites people to set a variable that does
  nothing.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Meta Open Source bot.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant