chemistry.toolsDocs
Search documentationSearch
Open workspace
GuidesGet started

Run your first job

Run a Python script locally, submit it to a remote worker and download its output files.

10 minRead as Markdown
Before you start

A repository checkout and uv. A project and worker for remote submission.

A completed remote job with logs and downloaded output files.

Run a Python script on your laptop first, then send the exact same file to a remote worker and download its output.

1. Install the CLI

Install the compute CLI (ct-cli) from the repository root:

bash
uv sync --project compute/platform --frozenalias ct-cli="$PWD/compute/platform/.venv/bin/ct-cli"ct-cli --help

Note: alias ct-cli=... applies to your current shell session. Add it to your shell profile or run compute/platform/.venv/bin/ct-cli directly in new terminals.

2. Run a script locally

We will use compute/platform/examples/hello.py, which writes its command-line arguments to results/hello.txt:

python
"""A tiny ordinary script for trying the local compute CLI."""
from __future__ import annotations
import sysfrom pathlib import Path
Path("results/hello.txt").write_text(" ".join(sys.argv[1:]) or "hello")

Run it locally with ct-cli run. Everything after -- is passed to sys.argv:

bash
ct-cli run compute/platform/examples/hello.py -- hello world

ct-cli run executes the script in an isolated attempt directory and prints the path to results/hello.txt:

text
State: succeededAttempt directory: .ct-cli/local-runs/...Output: results/hello.txt

No login or server connection is required for local runs.

3. Log in and select a worker pool

Authenticate with your account and inspect available workers:

bash
ct-cli loginct-cli worker list
text
ID                                    NAME         POOL  PLATFORM                   ENABLED0195f3a0-1234-7000-8000-000000000001  cpu-worker   cpu   linux-x86_64-py3.13-cpu    true

Save your default project, worker pool, and platform so you don't have to pass them on every command:

bash
ct-cli login --project PROJECT_UUID --pool cpu --platform linux-x86_64-py3.13-cpuct-cli whoami
  • Working over SSH? Add --no-browser to ct-cli login and open the printed URL on your laptop.
  • Using the local dev stack? Skip ct-cli login and use --config .local-dev/compute/client.json instead (see Use the local development stack).

4. Submit to a worker and download outputs

Submit the same script to your remote worker pool and wait for it to finish:

bash
ct-cli submit compute/platform/examples/hello.py --wait -- hello worker

Copy the returned JOB_UUID to inspect logs or download output files:

bash
ct-cli status JOB_UUIDct-cli logs JOB_UUIDct-cli fetch JOB_UUID --output ./job-output

Your downloaded file is saved at ./job-output/JOB_UUID/results/hello.txt:

  • Any file your script writes inside results/ is automatically uploaded when the job finishes.
  • Pressing Ctrl-C during --wait only stops waiting in your terminal—the worker keeps running. Run ct-cli cancel JOB_UUID if you want to stop the job itself.

5. Pipe JSON into scripts

By default, ct-cli prints human-readable summaries in a terminal. Pass --json (or pipe stdout to another command) when scripting:

bash
ct-cli status JOB_UUID --jsonct-cli jobs --limit 10

Next, turn a Python function into a reusable Program with validated inputs and outputs.