Quickstart — from your own machine

You don’t have to use a Carolina Cloud head container to drive a run. You can run Nextflow on your own machine — a laptop, an HPC login node, a CI runner, wherever Nextflow already lives — and point it at Carolina Cloud’s elastic pool with the nf-ccloud plugin.

The plugin is published to the Nextflow plugin registry, so there’s nothing to download or unpack — Nextflow fetches it on first use the moment your run declares nf-ccloud@1.0.0. The only thing you provide that a head gets automatically is a pipeline token.

When to use this

• You already run Nextflow somewhere and just want the elastic pool as a backend.
• You drive pipelines from CI/CD or your own scheduler.
• You want the driver on infrastructure you control.

The head-container path (Quickstart — with a head container) is simpler — everything is pre-wired. This path trades that convenience for running the driver wherever you like.

Pipeline tokens

A pipeline token is a scoped, expiring credential that lets one Nextflow run talk to Carolina Cloud — and nothing else. It’s the least-privilege alternative to your full account API key:

• It works only on the Nextflow pipeline endpoints — opening a run, allocating and resizing pool workers, dispatching tasks. It cannot touch billing, your other instances, your storage, or account settings.
• It expires — you choose the lifetime.
• If it leaks it can’t take over your account, and you can revoke it instantly.

A head container gets one injected for you as CCLOUD_API_KEY. Running externally, you create your own.

Create a token in the console

1. Open API Key in the console — the Pipeline Tokens section is on that page.
2. Under Expires in, choose a lifetime (1, 7, or 30 days) and click Create Pipeline Token.
3. Copy the token immediately — it’s shown only once. Carolina Cloud stores only a hash of it; if you lose it, just create another.

The same page lists your active tokens with their expiry, and a Revoke button. Revoke a token as soon as you’re done with it or suspect it’s exposed. (A token that’s currently driving a live run can’t be revoked out from under it.)

Manage tokens via the API

If you’d rather script it:

• POST /api/pipeline-token/ with body {"ttl_hours": <1–720>} (default 24) → returns the raw token once.
• GET /api/pipeline-token/ → your active (non-expired, non-revoked) tokens.
• DELETE /api/pipeline-token/<id>/ → revoke one.

Set up your machine

1. Install Nextflow. You need Nextflow 26.04.4 (recommended). That’s the only install step — the nf-ccloud plugin lives in the Nextflow plugin registry, so you don’t fetch or unpack anything by hand. Any run that declares nf-ccloud@1.0.0 — via the -plugins flag or a plugins { } block — makes Nextflow download and cache it from the registry on first use.

2. Write a nextflow.config. Unlike on a head, nothing is pre-wired, so you provide the whole thing — the executor, your token, and your bucket:

plugins { id 'nf-ccloud@1.0.0' }
process.executor = 'ccloud'

ccloud {
    apiKey   = secrets.CCLOUD_API_KEY               // your pipeline token (step 3)
    endpoint = 'https://console.carolinacloud.io'
}

workDir = 's3://my-bucket/nf-work/'

aws {
    accessKey = System.getenv('AWS_ACCESS_KEY_ID')
    secretKey = System.getenv('AWS_SECRET_ACCESS_KEY')
    region    = 'us-central-1'
    client { endpoint = 'https://s3.us-central-1.wasabisys.com' }
}

3. Provide the token. Keep it out of your config with a Nextflow secret (recommended):

nextflow secrets set CCLOUD_API_KEY '<the token you copied>'

and reference it as apiKey = secrets.CCLOUD_API_KEY (as above). Alternatively set apiKey = System.getenv('CCLOUD_API_KEY') and export the env var.

4. Run — exactly as anywhere, with the mandatory -plugins flag:

NXF_SYNTAX_PARSER=v1 nextflow run nf-core/rnaseq -r 3.22.2 \
  -profile test -plugins nf-ccloud@1.0.0 \
  --outdir s3://my-bucket/results/

Your machine is now the driver; the tasks run on Carolina Cloud pool workers exactly as they would from a head. (The two flags are still required — see Configuration.)

Keeping tokens safe

• Treat a pipeline token like a password — anyone holding it can start pipeline runs (and spend) on your account until it expires or you revoke it.
• Prefer short lifetimes and a Nextflow secret (or env var) over hardcoding it in a committed config.
• Use a fresh token per project or CI pipeline, and revoke ones you’re done with.