Install¶

To get started on a lightcone project, you need three things on your machine: Python 3.11+, the lightcone command line tool lc, and an agent-based CLI (currently supporting Claude Code).
A container runtime is optional but recommended.

1. Python¶

If you don't already have a recent Python

brew install python@3.12

curl -LsSf https://astral.sh/uv/install.sh | sh
uv python install 3.12

module load python      # NERSC Python (3.11+)

conda create -n your-env-name python=3.11 -y
conda activate your-env-name

conda deactivate
mv ~/.conda/envs/your-env-name $SCRATCH/conda-envs/
ln -s $SCRATCH/conda-envs/your-env-name ~/.conda/envs/your-env-name

curl -LsSf https://astral.sh/uv/install.sh | sh

uv python install 3.12

2. lightcone-cli¶

The published name on PyPI is lightcone-cli; the command it provides is lc.

uv tool install lightcone-cli

python -m pip install lightcone-cli

uv tool install lightcone-cli

# NERSC python module
module load python
python -m pip install --user lightcone-cli   # lands in ~/.local/bin/

# Conda env
conda activate your-env-name
python -m pip install lightcone-cli

git clone https://github.com/LightconeResearch/lightcone-cli.git
uv pip install -e ./lightcone-cli

git clone https://github.com/LightconeResearch/ASTRA.git
uv pip install -e ./ASTRA

Get a confirmation of the proper installation by running

lc --version                # → lightcone-cli, version ...

Note Some people may have already set a personal shell alias lc='ls --color'. If that's you, installing lightcone-cli will shadow the alias — make sure to rebind it (e.g. alias l='ls --color').

3. Global configuration¶

~/.lightcone/config.yaml is created automatically the first time you run an lc subcommand. No manual setup step is needed. The file starts as:

container:
  runtime: auto
slurm:
  account: null
  time_padding: 1.5

auto detects whichever of podman, docker, or podman-hpc is on your PATH (and skips docker if its daemon isn't running). Feel free to pin the runtime later by editing this file directly. Before the first lc run --async, replace slurm.account: null with the SLURM project to charge; synchronous and local work do not require it.

4. Agentic CLI¶

Most of your interactions with a lightcone project happen through an agent-based CLI. Any agent that can drive a project shell works — the choice is yours.

curl -fsSL https://claude.ai/install.sh | bash

claude --version
claude        # first run prompts for login (claude.ai or API key)

curl -fsSL https://opencode.ai/install | bash

Open a project in your terminal or editor (see Getting Started) and run your agent CLI from inside it. Inside Claude Code you'll type slash commands like /lc-new, /lc-from-code, and /lc-from-paper — see The Agentic Workflow.

5. (Optional) Docker or Podman¶

If your analysis declares a container: (which it usually should — it makes the result reproducible across machines), you need a container runtime:

• Local laptop: install Podman (rootless, no daemon) or Docker.
• HPC login node: see Running on a Cluster.

The auto mode picks whichever container runtime you have. If you don't have either, you can still use lc — set runtime: none in ~/.lightcone/config.yaml and recipes will run on the host without isolation.

Sanity check¶

lc --help
lc init --help

Both should print help text. If lc is shadowed by an ls alias, unset it (unalias lc) or use the full path ($(which lc) --version).

Updating¶

uv tool upgrade lightcone-cli

pip install -U lightcone-cli astra-tools

cd path/to/lightcone-cli
git pull
uv pip install -e .        # only needed if pyproject.toml changed

Uninstalling¶

uv tool uninstall lightcone-cli

pip uninstall lightcone-cli