Run a project command

Start with a recommendation

amics gpu recommend \
  --gpu auto --gpus 1 --min-vram 24 \
  --preference balanced --max-runtime 30m

--preference accepts balanced, cost, or speed. A recommendation is read-only.

Execute

amics run \
  --project fine-tune \
  --source . \
  --gpu auto --gpus 1 --min-vram 24 \
  --max-hourly-price 1.50 --max-runtime 30m \
  --yes \
  -- uv run train.py

The project name creates a stable reuse identity. The source defaults to the current directory.

Literal arguments and shell behavior

Arguments after -- are passed as literal process arguments. Pipes, redirects, globs, expansion, and command chaining do not happen implicitly.

Use a shell explicitly when shell behavior is part of the command:

amics run [OPTIONS] -- sh -lc 'uv run train.py | tee remote.log'

Source snapshots

Inside Git, the snapshot includes tracked and untracked files after standard ignore rules and .amicsignore. Amics excludes .git, common secret files, unsafe links, and traversal paths; .amicsignore can exclude a symlink before it is selected. Outside Git, traversal rejects any symlink before .amicsignore can filter it, so remove or relocate the link or snapshot a Git worktree instead.

Each run receives an immutable snapshot. Remote changes do not overwrite the local source tree and are not used in the next run.

Environment values

Forward values explicitly by local name:

export DATA_TOKEN=...
amics run [OPTIONS] --env DATA_TOKEN -- python train.py

Repeat --env for multiple names. Do not put secrets in command arguments.

Output modes

Only one of --quiet, --json, or --jsonl may be selected. Detaching does not extend the server deadline.

Reuse compute briefly

amics run [OPTIONS] --keep-warm 10m -- uv run train.py

A warm lease lets later compatible commands with the same project reuse the machine and its project cache. The lease expiry is calculated from each run's completion time, so repeating the full --keep-warm duration can extend the approved billing window. For multiple experiments, request the warm lease on the first run, capture its compute_id, and use that ID without --keep-warm on later runs:

amics run --compute COMPUTE_ID --max-runtime 10m -- uv run train.py

It is bounded and can still end early if Spot capacity is interrupted. Without --keep-warm, auto-acquired compute stops after the command.

Use --compute COMPUTE_ID to run on compute you already control. Amics will not stop user-supplied compute implicitly.