chemistry.toolsDocs
Search documentationSearch
Open workspace
GuidesRun and operate

Use the local development stack

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

10 minRead as Markdown
Before you start

macOS or Linux with local development prerequisites installed.

A running local stack that executes jobs end to end.

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 listct-local program listct-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_UUIDct-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 Pathfrom 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 credentialsct-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.