---
title: "Prepare your arx.yaml"
description: "Declare the platform resources your application needs in arx.yaml: the model API gateway, networking, storage, and desktop shortcuts, and how their connection details reach your pods"
canonical_url: "https://developer.ardge.com/en/guide/isv/prepare-arx-yaml"
---
# Prepare your arx.yaml

> Declare the platform resources your application needs in arx.yaml: the model API gateway, networking, storage, and desktop shortcuts, and how their connection details reach your pods

## Overview

`arx.yaml` is where your application asks the platform for what it needs. The platform provisions those resources at install time and injects their connection details into your pods, so model access, networking, storage, and the desktop entry are wired in rather than configured by hand on site.

This page covers the blocks you declare there. Making the chart hold up its end comes next.

## What you'll learn

- How your workload receives the model API endpoint and key
- How to declare the network and storage your application needs
- How to put your application on the ARX desktop

## Applies to

- ARX OS 1.0 and later

## Before you begin

- Your application is packaged as a container image, and that image can be pulled from an address the ARX system can reach
- You know which ports your application serves, which volumes it needs, and whether it calls a model

Download the skills before you start. You write `arx.yaml` through them, and each section below points at the reference they carry: `arx-marketplace-templates/references/arx-binding.md`.

<note>

**Download the skills:** the bundle is [arx-isv-skills-v0.6.4.zip](https://developer.ardge.com/skills/arx-isv-skills-v0.6.4.zip) (about 185 KB) — unzip it and copy the folders inside into your project's `.claude/skills/`.

</note>

<tip>

**Let an AI agent write arx.yaml for you:** once you have settled which platform resources your application needs, the `arx-marketplace-templates` skill writes the file against the schemas it ships with. Prompt it with the resources rather than the YAML, for example: `use arx-marketplace-templates to write arx.yaml for my app: an HTTP service on port 5678, one 10Gi read-write volume, the AI gateway injected as OPENAI_API_BASE_URL and OPENAI_API_KEY, and a desktop shortcut that opens it in an iframe`.

</tip>

## What `arx.yaml` declares

`arx.yaml` sits next to your manifest and is the contract between your application and the platform: you declare the platform resources you need, the platform provisions them and injects the connection details into your pods.

```yaml
apiVersion: arx.ardge.com/v1
kind: ArxBinding
spec:                    # at least one block
  network: { ... }
  storage: [ ... ]
  desktop: { ... }
  ai: { ... }
```

Two conventions run through most blocks:

- `components` targets pods by their `app.kubernetes.io/component` label. Leave it out to inject into every pod of the release
- `inject` maps a platform field to the environment variable your application reads it from, and the variable name must be `UPPER_SNAKE_CASE`

Each section below names the block to read in `arx-binding.md`.

## Model API injection

The `ai` block hands your workload the platform's AI gateway: an OpenAI-compatible base URL and key, injected as the environment variables you name.

```yaml
spec:
  ai:
    components: [worker]
    inject:                      # both required
      baseUrl: OPENAI_API_BASE_URL
      apiKey: OPENAI_API_KEY
```

Read the `ai` section of `arx-binding.md` for the full field list. For what those values are and how an application uses them, see [Call on-premises models on ARX through the API](https://developer.ardge.com/en/guide/isv/api-model-calls).

## Network settings

The `network` block declares the Kubernetes Services your application needs. Every key under `network.services` becomes a `serviceRef` that the other blocks point at, so this block usually comes first.

Read the `network` section of `arx-binding.md`.

## Storage settings

The `storage` block binds your chart's persistence settings to platform-managed PVCs — one entry per storage slot, each naming the slot, the template that renders the PVC name, and whether access is read-write or read-only.

Read the `storage` section of `arx-binding.md`.

Remote storage is mounted on the device side first. See [Mount remote storage for an application in Storage Manager](https://developer.ardge.com/en/guide/isv/mount-remote-storage) for that procedure.

## Desktop shortcuts

The `desktop` block puts your application on the ARX desktop: up to four shortcuts, each with a label, whether it opens in an iframe or a new tab, and the service and path it points at.

```yaml
spec:
  desktop:
    shortcuts:
      - label: my-app
        open: [iframe, newtab]
        serviceRef: http
        scheme: http
        path: /
```

Read the `desktop` section of `arx-binding.md`.

## Next step

<card-group>
<card icon="i-lucide-box" title="Prepare your Helm chart" to="https://developer.ardge.com/en/guide/isv/prepare-helm-chart">

Package the chart these bindings reach into, and expose the labels and persistence values they rely on

</card>
</card-group>


## Sitemap

See the full [sitemap](https://developer.ardge.com/sitemap.md) for all pages.