Quickstart¶

In a "Phase 1" configuration, you will be configuring your agent and your runner yourself. This (most likely) means one setup on your local computer, one on the hpc, assisted by atomatic configure.

The agent makes decisions. jobflow-remote's runner manages computations.

\(\alpha\): Prerequisites¶

Step 1. Determine where you want the agent/runner to run¶

To start, we recommend running the agent on your laptop, or some always on-computer you will have access to without network restrictions.

We recommend running the runner as a cronjob on your HPC system. Other configurations are also acceptable, but we endorse putting the runner on the HPC in some "always on" fashion. For HPCs with extremely strict security rules, this may need to be changed.

From here on, we will refer to the computer with the agent on it as agent computer and the computer with the runner on it as the runner computer.

Step 2. Get a mongodb¶

The mongodb must be accessible from the runner computer.

Obtain the URI string with and keep it handy for a moment. Example: mongodb://username:password@mongodb07.nersc.gov/mydb

Step 3. Get your agent's model API key¶

If you are using Anthropic/OpenAI, this consists only of your API key. Go to the next step.

If you are using a third-party vendor like CBORG or a self-hosted model, this will require determining if the API-specification is OpenAI- or Anthropic- compatible. You'll need 3 pieces of info:

• The spec type (openai or anthropic)
• Your custom provider's API key
• Your custom provider's URI (eg https://api.cborg.lbl.gov)

Step 4: Determine the model you want to run¶

If you are just running anthropic or OpenAI models directly with one of their API keys, this is as easy as anthropic:claude-sonnet-5 or openai:gpt-5.6-sol

With a custom provider, the model string may be different, such as openai/gpt-5.5 or lbl/cborg-chat. If you are using cborg, see here.

\(\beta\): Configure runner computer (HPC)¶

Step 1: Ensure you have prerequisite paths and software¶

• DFT binary: For DFT, ensure you have access to VASP or other binary executable and know the modules needed to run your preferred version (s) eg. vasp/6.4.2-gpu
  • Pseudopotentials: Make sure your pseudopotentials are in a pymatgen compatible format in an accessible, known directory. Documentation shows how to convert your PSP dir structure if needed. PMG_VASP_PSP_DIR is the relevant environment variable.
• uv venv: Ensure you can make python venvs, uv installation preferred.

Step 2: Install atomatic¶

For sanity sake, we'll keep as much as we can inside the $HOME/atomatic directory. Install atomatic into the venv which the runner will use.

mkdir $HOME/atomatic && cd $HOME/atomatic
git clone https://github.com/forum-ai/atomatic
uv venv atomatic-env --python 3.12
source atomatic-env/bin/activate
uv pip install -e atomatic

Step 3: Run atomatic configure¶

With the venv active:

cd atomatic && atomatic configure

Pick "runner computer" and answer the questions. Enter takes the shown default, and < goes back. It configures the active venv: it installs only the atomatic and atomate2 extras you pick which the venv does not have yet (installed ones show a gray [x]), and fills the paths in the cron scripts from this venv. It then lists every file it will write and every command it will run, flags anything it would overwrite, and does nothing until you answer y (< there returns to the questions). It also checks the MongoDB connection, initializes the jfremote db if empty, applies the (s)crontab, and checks that the cron job starts the runner.

In case atomatic configure doesn't work for you, manual steps are below in appendix 1.

\(\gamma\): Configure agent computer (your laptop)¶

Step 1: Install atomatic¶

git clone https://github.com/forum-ai/atomatic
uv venv atomatic-env --python 3.12
source atomatic-env/bin/activate
uv pip install -e atomatic

Step 2: Run atomatic configure¶

With the venv active:

cd atomatic && atomatic configure

Pick "agent computer". It installs the atomatic and atomate2 extras you pick which the active venv does not have yet, writes .env, and reminds you to copy the jobflow-remote config over from the runner computer. Manual steps are in appendix 2.

To skip questions, pass .env values with --set, e.g. atomatic configure --set ATOMATIC_MODEL_NAME=openai:gpt-5.6-sol.

\(\delta\): Run it¶

See run.md for instructions on how to run the agent and runner.

Appendix 1: Manual configuration steps for runner computer¶

For this section, ensure you are on the runner computer (HPC, most likely).

Step 1: Set up uv venv in desired directory¶

mkdir $HOME/atomatic && $HOME/atomatic
git clone https://github.com/forum-ai/atomatic
uv venv atomatic-env --python 3.12
source atomatic-env/bin/activate

Step 2: Install requirements¶

Note while you do not actually need atomatic installed on the HPC, you do need many of the same requirements as atomatic.

cd atomatic
uv pip install --group runner

This installs atomate2 from its main branch. Add any atomate2 extras you need, e.g. uv pip install "atomate2[phonons]". The list of extras is in the pyproject.toml of atomate2. Use the same extras on the agent computer.

Step 3: Change configuration options and desired paths¶

Assuming you already have atomatic downloaded, go to atomatic/atomatic/cli/configure/ and find your hpc's directory; if your hpc is not listed, find one like it.

cd atomatic/atomatic/cli/configure/hpc-nersc

There are several files in this directory. Find-and-replace the following configurable options as needed for your use case across all of the files.

HPC: important configuration options¶

Configurable options:

Hard-coded configuration paths:

Step 4: Set up jfr config¶

With the configuration values replaced, copy the jfr-atomatic-template.yaml into the ~/.jfremote directory and rename it to the same thing as your project name, eg atomatic-001.yaml.

mkdir -p ~/.jfremote
cp jfr-atomatic-template.yaml ~/.jfremote/atomatic-001.yaml

Step 5: Set up jfr cron runner¶

First, make the shell scripts executable:

chmod +x jfr_cron_runner_*.sh

Then, copy the crontab file and jfr_cron_* scripts to CHANGEME_JFR_CRON_DIR. For simplicity, we'll just keep everything in $HOME/atomatic/jfr_cron

mkdir $HOME/atomatic/jfr_cron
cp *crontab.txt jfr_cron_runner_*.sh $HOME/atomatic/jfr_cron

Then, using your (s)crontab utility, apply the (s)crontab.txt to your crontab.

scrontab scrontab.txt

Last, check that the cron job starts the runner:

$HOME/atomatic/jfr_cron/jfr_cron_runner_check.sh

Appendix 2: Manual configuration for the agent computer¶

Step 1: Install atomatic¶

Needs Python 3.12 or newer.

git clone https://github.com/forum-ai/atomatic
uv venv atomatic-env --python 3.12    # next to the clone, like on the runner
source atomatic-env/bin/activate
cd atomatic
uv pip install -e .          # atomatic and all its dependencies
cp atomatic/.env.example atomatic/.env   # then edit it, see below

Add .[dev] instead of . to also get ruff and the local chat server. Add the same atomate2 extras you installed on the runner, e.g. uv pip install -e . "atomate2[phonons]", or the same main clone, uv pip install -e . -e "../atomate2[phonons]".

Step 2: Configure atomatic with .env¶

Everything for atomatic is configurable in .env, in the atomatic package dir (atomatic/.env in a clone). These values only supplement your real environment variables, and never replace them.

Atomatic-specific configuration¶

Provider-specific configuration¶

LLM provider env vars: Only set these to supplement the API keys in your environment, or if you have not set them there.

LLM tools: Again, only set these to supplement your current env.

Other useful configuration¶

Atomatic does not need access to these, but may make good use of them. These may be defined in your environment or in .env.

Step 3: Copy jfremote configuration from HPC¶

Copy the jfremote configuration from your HPC (Appendix 1, Step 4 above) into ~/.jfremote on your agent machine.

scp it back to your local machine

# on agent machine
scp me@hpc:/path/to/.jfremote/atomatic-001.yaml ~/.jfremote/atomatic-001.yaml

Alternatively, just copy/paste the data into your local ~/. jfremote/atomatic-001.yaml

Step 4: Setting HPC credentials¶

Your agent can most easily log into HPCs if you store credentials in:

a. In an .env file, or
b. MacOS: Keychain, eg. via security add-generic-password, or
c. Linux secret-tool or similar

No specific naming is required, the agent will infer it.

If you choose (b) or (c), it may help to put the names of required login items (e. g., NERSC_PASSWORD) in the .env file, as well as a hint (no specific syntax required) for the agent to infer what kind of keychain it is stored under (e.g., USE_APPLE_KEYCHAIN=1 or similar)