# 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](https://docs.cthree.cloud/environment.md).

**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](https://docs.cthree.cloud/data-mounting.md).

**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](https://docs.cthree.cloud/artifacts.md).

## Configuration reference[​](#configuration-reference "Direct link to 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 | GPU profile (use `l40` for new jobs; A100/H100 profiles are temporarily unavailable for non-admin submissions). See `c3 list`                                                                   |
| `provider`       | string | Optional compute provider pin from `c3 list`. Omit it to let C3 auto-route across available marketplace providers; set it only when you need to force a provider 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](https://docs.cthree.cloud/data-mounting.md)                                                                                   |
| `output`         | list   | Directories to collect as artifacts. See [Artifact Output](https://docs.cthree.cloud/artifacts.md)                                                                                              |

## Full example[​](#full-example "Direct link to 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.

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

See [Environment](https://docs.cthree.cloud/environment.md) for Python, Docker, and Bash-only examples.

## Creating a new project[​](#creating-a-new-project "Direct link to 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[​](#api-keys "Direct link to 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.