Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.
AgentsAutomationLlm

Using Artifacts with AI agents

What Harness Artifacts is, how to authenticate, what URLs to use, and which operations are available, written for AI agents and LLMs.

For AI agents and LLMs

This page is written to be consumed directly by an AI agent. It covers authentication, URL patterns, available operations, REST API endpoints, and supported formats in a dense, copy-paste-ready format. If you are an agent reading this, start at Authentication and work top to bottom.

What Harness Artifacts is

Harness Artifacts is a universal artifact storage service. It hosts Docker images, Helm charts, npm packages, Python wheels, Maven JARs, Go modules, Cargo crates, NuGet packages, Terraform modules, Hugging Face models, generic files, and more in a single system.

A registry is a named namespace inside a Harness account. Each registry hosts one package type. The registry URL follows a predictable pattern:

pkg.harness.io/<ACCOUNT_ID>/<REGISTRY_NAME>

The REST management API lives at a separate host:

https://app.harness.io/har/api/v1

Authentication

One API key authenticates every operation: package manager clients, the REST API, and the CLI.

export HARNESS_API_KEY="<pat-or-service-account-token>"
export HARNESS_ACCOUNT_ID="<account-id>"        # from app.harness.io URL: /ng/account/<ID>
export HARNESS_EMAIL="<harness-account-email>"  # only needed for PAT auth; service accounts use "_token" as username
export HAR_REGISTRY="<registry-name>"
Context
How to pass the key

REST API calls

x-api-key: $HARNESS_API_KEY header

Package manager clients: service account

password = $HARNESS_API_KEY, username = _token (literal string)

Package manager clients: PAT

password = $HARNESS_API_KEY, username = $HARNESS_EMAIL

hc auth login

--api-token $HARNESS_API_KEY

All other hc commands

--token $HARNESS_API_KEY or HARNESS_API_TOKEN env var

Kubernetes imagePullSecret

username = _token, password = $HARNESS_API_KEY

Use a Service Account Token, not a Personal Access Token, for any non-interactive agent. PATs are tied to a user identity.

Verify the token works:

Expected: 200. 401 = bad token. 403 = token valid but no registry permissions.


Registry URL patterns

Docker and OCI clients use pkg.harness.io/<ACCOUNT_ID>/<REGISTRY> directly. All HTTP-based package manager clients (npm, Maven, Python, Cargo, etc.) use https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY>; note the extra /pkg/ path segment after the hostname.

Format
Registry URL suffix
Example

Docker / OCI

(none)

pkg.harness.io/<ACCOUNT_ID>/<REGISTRY>

Helm OCI

(none, same as Docker)

oci://pkg.harness.io/<ACCOUNT_ID>/<REGISTRY>

npm

/npm/

https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY>/npm/

Python / PyPI

/python/

https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY>/python/

Maven

/maven

https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY>/maven

Go modules

(inline in GOPROXY)

https://_token:<TOKEN>@pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY>/go

Cargo

/cargo/index/

sparse+https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY>/cargo/index/

NuGet

/nuget/index.json

https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY>/nuget/index.json

Hugging Face

/huggingface

https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY>/huggingface

Generic / HTTP

/generic/<NAME>/<VERSION>

https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY>/generic/<NAME>/<VERSION>

Terraform modules

/terraform

https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY>/terraform

RPM

/rpm

https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY>/rpm

Debian / APT

/deb

https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY>/deb


Core operations

Check if an artifact exists

Push an artifact

Pull an artifact

Delete an artifact version

Go to API quickstart for agents for the full per-format command reference.


REST management API

Base URL: https://app.harness.io/har/api/v1

All requests: x-api-key: $HARNESS_API_KEY

Key endpoints

Copy-paste examples:

Go to REST API reference for all endpoints and schemas.


Supported formats

26 formats across 12 ecosystems:

Ecosystem
Formats

Container

Docker, Helm OCI, Helm HTTP

JVM

Maven, Gradle

JavaScript

npm

Python

Python / PyPI

.NET

NuGet

Rust

Cargo

Go

Go modules

AI / ML

Hugging Face

Infrastructure

Terraform modules, Terraform Backend

OS packages

RPM, Debian / APT, Alpine / APK, Wolfi / APK

Languages

PHP Composer, Dart, Swift, Ruby / RubyGems, R / CRAN, Conan, Conda, Puppet

Generic

Generic / Raw

Go to Supported formats for the full list including GA status.


Patterns for AI agents

Storing build outputs

An agent that generates and builds code can push build artifacts directly to Harness Artifacts:

Checking before building

Before triggering a build, check if the artifact already exists in the registry:

Storing and retrieving model weights

For Hugging Face format registries, set HF_ENDPOINT to route model downloads through Artifacts:

This routes model downloads through your Artifacts registry, enabling offline environments, caching, and version pinning for model weights.

Routing package dependencies through Artifacts

Point package managers at Artifacts to route all dependency resolution through your registry (useful for supply-chain control):

An upstream proxy registry forwards requests for packages not yet in Artifacts to the configured public registry (npm, PyPI, etc.) and caches them on first pull.

Querying what is available


HTTP status codes

Code
Meaning
Action

200

OK

—

401

Bad or missing token

Check $HARNESS_API_KEY; regenerate if expired

403

Insufficient permissions

Add Artifact Registries: Pull or Push permission to the service account

404

Resource not found

Check $HAR_REGISTRY, $HARNESS_ACCOUNT_ID, artifact name, and version

409

Already exists

Use a new version tag, or delete the existing version first

413

Payload too large

Generic registry max is 5 TiB per file

429

Rate limit exceeded

Back off and retry; limit is 1,000 requests/min per API key


Next steps

Last updated

Was this helpful?