Project Configuration

C3 projects are configured with a .c3 YAML file at the project root. Run c3 deploy from anywhere in the project to submit a job.

Key differences from running locally

Environment: Every job runs a Bash script. Use python: or docker: when you want C3 to prepare the environment; omit both for Bash-only jobs where setup happens inside the script each time. See Environment.

Data mounting: Your data lives in C3's centralised storage. You tell C3 which datasets to mount and where using datasets:. Your script reads from that path as if the files were local. See Data Mounting.

Artifact output: Files on the GPU are discarded when the job ends. Write results to $C3_ARTIFACTS_DIR or a directory listed in output:. Only these are collected. See Artifact Output.

Configuration reference

Field	Type	Description
project	string	Project name (auto-generated if not set). Lowercase alphanumeric + hyphens.
script	string	Required. Path to a bash script with your execution commands (e.g. run.sh), relative to .c3
gpu	string	Optional GPU profile. Omit it or set l40, a100, or h100 to let C3 pick within that public class and charge the selected provider/profile rate. Run c3 list for public class ranges and c3 list -al for concrete profile codes; exact profiles such as l40s-d-32x192 or h100-80gb pin that class member.
provider	string	Optional compute provider pin. Omit it to let C3 auto-route across available marketplace providers; set it only when C3 support or runbooks have given you a provider id such as nextgen or nebius.
time	string	Maximum runtime in HH:MM:SS format. You're only charged for actual usage
job_name	string	Job display name
python.project	string	Path to Python project dir with pyproject.toml + uv.lock. Mutually exclusive with docker:
docker.image	string	Public Docker Hub image reference to pull on the GPU VM. Mutually exclusive with python:
datasets	list	Datasets to mount (ref + optional mount). See Data Mounting
output	list	Directories to collect as artifacts. See Artifact Output

Full example

All job configuration goes in .c3. The script field points to a bash script containing your execution commands — no #SBATCH or #C3 directives needed.

# .c3
project: my-experiment
script: run.sh
gpu: l40
time: "04:00:00"
job_name: train-model

python:
  project: ./

datasets:
  - ref: /datasets/imagenet
    mount: /data/imagenet

output:
  - ./checkpoints
  - ./results

To pin a provider, add provider: or pass c3 deploy -p <provider>. Pinned providers still pass through the same route-preview, stock, inventory, and spend guard checks as auto-routed jobs.

Machine-readable deploy output

Use c3 deploy --json when an automation script needs to submit a job and parse the result. --json cannot be combined with -f or --follow; submit first, then use c3 squeue --json or c3 deploy -f without --json for live logs.

In JSON mode, stdout contains one JSON object after successful submission. Human progress output is suppressed, and warnings are suppressed or written to stderr so stdout remains parseable.

c3 deploy --json

The response includes:

Field	Description
id	Submitted job ID
status	Initial job status returned by the API
provider	Selected provider ID, if the API assigned one at submission time
region	Selected provider region; may be null when no region has been assigned yet
gpu_profile	Selected concrete GPU profile, if assigned
route.pool	Provider/region/GPU route string using the fields available on the created job
route.warm_pool_hit	null until the API reports an explicit warm/cold dispatch signal; reserved for future use
dashboard_url	Dashboard URL for the submitted job
pull_command	c3 pull <job_id> command for downloading artifacts after the job completes

# run.sh
#!/bin/bash
python3 train.py

See Environment for Python, Docker, and Bash-only examples.

Creating a new project

cd my-project
c3 init

This creates a .c3 file with sensible defaults. Edit it and deploy with c3 deploy.

API keys

For team billing or CI/CD, add an API key to .c3.local (keep this file out of version control):

# .c3.local — secrets (add to .gitignore)
api_key: c3_key_abc123def456...

Create keys with c3 apikey create my-team-key. API keys are scoped to the org that created them, and deploy uploads are stored under that same org. Create and use the key from the org that should own the project and job.

The API key takes priority over c3 login credentials. You can also set it with:

export C3_API_KEY=c3_key_abc123def456...

Use c3 whoami to verify the active credential and org before deploying. If a key was pasted into a shared shell, CI log, or support thread, revoke it with c3 apikey revoke <key-id> and create a replacement.