# Use the local development stack

Start the local API, database, scheduler, storage and CPU worker on your machine.

Start an isolated local stack (API server, PostgreSQL, Keycloak, Hatchet scheduler, S3-compatible storage, and a CPU worker) on your machine to test jobs end to end without production credentials.

## 1. Start the local compute stack

Make sure you have completed the native prerequisites in `development/GUIDE.md`, then run:

```bash
./dev setup --compute
./dev up --compute
./dev status
```

- **`./dev setup --compute`** installs dependencies and generates local credentials in `.local-dev/` (only needed on first setup or after dependency updates).
- **`./dev up --compute`** starts all services plus a local CPU worker.
- **`./dev down`** stops the services while keeping your local database and storage intact.

## 2. Submit a job using the generated local config

`./dev setup --compute` automatically writes a ready-to-use client connection file at `.local-dev/compute/client.json`. Create an alias that points `ct-cli` at that config:

```bash
alias ct-local="ct-cli --config .local-dev/compute/client.json"

ct-local worker list
ct-local program list
ct-local submit compute/platform/examples/hello.py --wait -- local roundtrip
```

> **Note:** Always place `--config .local-dev/compute/client.json` **before** the subcommand (`worker`, `program`, `submit`). Using a separate config file leaves your normal `ct-cli login` session untouched.

## 3. Fetch logs and output files

Pass the returned `JOB_UUID` to `logs` and `fetch`:

```bash
ct-local logs JOB_UUID
ct-local fetch JOB_UUID --output ./local-output
```

Verify that `./local-output/JOB_UUID/results/hello.txt` contains `local roundtrip`.

To use the same local connection from Python, pass the path to `Client.from_login()`:

```python
from pathlib import Path
from chemistry_compute import Client

client = Client.from_login(Path(".local-dev/compute/client.json"))
job = client.submit_script(Path("compute/platform/examples/hello.py"))
print(job.result(timeout=300))
```

## 4. Test interactive browser login (optional)

You only need `.local-dev/compute/client.json` for normal job development. If you specifically want to test the interactive browser OAuth flow against your local Keycloak and API server:

```bash
./dev credentials
ct-cli --config .local-dev/browser-login.json login \
  --server https://api.chemistry.test:8443 \
  --ca-file .local-dev/rootCA.pem
```

## 5. Reloading local code changes

- **Scripts and managed `uv` packages:** Changes are picked up automatically on your next `submit` or `program publish --version N`.
- **Shared native runtime (`compute/runtime`):** Because the local worker verifies its installed environment fingerprint, stop the worker (`./dev down`) before editing or syncing packages in `compute/runtime`, then follow `compute/runtime/GUIDE.md`.