> For the complete documentation index, see [llms.txt](https://docs.kinesis.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kinesis.network/api/app-configuration.md).

# App configuration

Understand app configuration, defaults, secrets, updates and deployment outcomes.

The Apps API accepts a `config` object for container runtime, network and resource requirements. For image apps, provide `config.image`. For repository apps, provide `source` and omit the image; the build determines it.

## Configuration groups

| Field                   | Purpose                                                   |
| ----------------------- | --------------------------------------------------------- |
| `image`, `registryAuth` | Image reference and optional private-registry credentials |
| `ports`                 | Container ports and exposure protocols                    |
| `env`                   | Environment variables and write-only secrets              |
| `command`, `entrypoint` | Container CMD and ENTRYPOINT overrides                    |
| `startupCommand`        | Command executed inside the container after startup       |
| `healthcheck`           | Check command and interval                                |
| `restartPolicy`         | Restart behavior, failure tolerance and task completion   |
| `instances`             | Minimum and maximum container count                       |
| `stateful`              | Pin an instance to its server and disk                    |
| `hardware`              | GPU requirements, RAM, disk and shared memory             |
| `placement`             | Allowed regions, providers and source IPs                 |
| `grids`                 | Grid IDs and priorities                                   |
| `volumes`               | Named persistent mounts for grid apps                     |

The [Apps reference](/api/apps.md) contains every nested field, type and supported enum. Runtime validation and capacity checks still apply after schema validation.

## Organization and compute permissions

Apps belong to their project’s organization and inherit its visibility. Developers can create and operate apps they can edit; only admins or an app’s creator can delete or move it. Grid targeting requires permission to deploy to the grid. Developers must target an accessible grid when `serverlessEnabled` is off. Grid quotas count live placements against the app’s creator; policy management is in the portal.

Serverless placement is CPU-only. A positive `hardware.gpuCount` requires at least one `grids.ids` entry. Older serverless GPU apps must move to a grid or remove the GPU requirement before their next configuration update; domain attachment/removal can encounter the same validation.

## Defaults and units

When omitted on creation, the current defaults are 1 GiB RAM, 1 GB disk, one to three instances, no GPU, any region and 64 MiB shared memory. Set instance bounds explicitly when a workload should use exactly one instance.

App hardware memory and storage fields use **bytes**. Dedicated-server provisioning uses `storageSizeGb`, while billing amounts use **US cents**. Do not interchange these units.

## Secrets

```json
{
  "env": [
    {"key": "MODEL_NAME", "value": "your-model"},
    {"key": "MODEL_TOKEN", "value": "<secret-value>", "secret": true}
  ]
}
```

Secret values are write-only and return null in reads. On update, null preserves the stored value of any existing variable. New variables need a value. Registry passwords are also write-only; reads expose the registry username separately.

## Update semantics

| Input                                       | Update behavior               |
| ------------------------------------------- | ----------------------------- |
| Omitted field                               | Keeps the stored setting      |
| Lists such as `env`, `ports`, `volumes`     | Replaces the entire list      |
| `hardware`, `placement`                     | Merges supplied keys          |
| `instances`                                 | Requires both `min` and `max` |
| `grids.priorities`                          | Replaces the priorities map   |
| `healthcheck: null`, `startupCommand: null` | Clears the setting            |
| Existing variable with `value: null`        | Preserves its stored value    |

Read configuration before editing arrays, and serialize concurrent writers. Changing compute sizing or build source can require `compute:spend`. Updating a running app may redeploy it.

The [OpenAI MCP profile](/mcp/openai-profile.md) does not accept registry credentials or secret environment values; set them in the portal. It also hides credential-like environment values on reads. Standard REST and MCP schemas below retain their supported credential fields.

## Repository source

```json
{
  "name": "service",
  "source": {
    "kind": "github",
    "installationId": 12345678,
    "repo": "your-org/your-repo",
    "branch": "main",
    "dockerfilePath": "Dockerfile",
    "contextDir": ".",
    "autoDeploy": true
  },
  "config": {
    "ports": [{"port": 3000, "protocol": "http80_load_balancer"}],
    "instances": {"min": 1, "max": 1}
  }
}
```

The identifiers above are placeholders. Discover the actual installation and repository with the [GitHub API](/api/github.md). An inline `dockerfileContent` can supply the Dockerfile. Updates to build source return the ID of the rebuild they trigger; poll the build and then app status.

## Additional creation options

### Copy environment variables from another app

On creation, use `envFrom` to copy variables and secret values on the server. The caller needs Developer access to the source app as well as permission to create in the destination project. This takes a copy once; future changes to the source app do not propagate.

```json
{
  "name": "web-copy",
  "config": {"image": "nginx:stable", "instances": {"min": 1, "max": 1}},
  "envFrom": {
    "projectId": "507f1f77bcf86cd799439011",
    "appId": "507f1f77bcf86cd799439012",
    "overrides": [{"key": "APP_ENV", "value": "staging"}]
  }
}
```

Replace the example IDs with the app to copy. Omit `config.env` when using `envFrom`; use `overrides` instead. Overrides match by key. A null value preserves the copied value, and a copied secret remains secret. If the source has no available configuration, the API returns `409 app_config_unavailable`.

### Clone a public GitHub repository

For a new repository-backed app, choose exactly one of `source.repo` or `source.clone`:

```json
{
  "name": "service-copy",
  "source": {
    "kind": "github",
    "installationId": 12345678,
    "clone": {
      "sourceRepo": "example-org/example-service",
      "targetRepoName": "my-service",
      "targetVisibility": "private"
    }
  },
  "config": {"instances": {"min": 1, "max": 1}}
}
```

Replace the installation and repository with real values. The source must be public. `sourceRepo` accepts `owner/name` or a GitHub URL, optionally with `/tree/<branch>`; `sourceRef` can select a branch, tag or commit. The destination is created in the connected account and defaults to private visibility. A member of the project’s organization with permission to edit it can make this request. Omit `config.image` and `config.registryAuth`; the build supplies the image.

Cloning runs in the build's `vcs_import` step. Follow the returned build ID, inspect errors or logs, and then poll app status. `browse_github` / the GitHub contents API can inspect source files; `source.dockerfileContent` supplies an inline Dockerfile if needed.

## Placement and project moves

Check placement before creating an app with `POST /projects/{projectId}/placement`, or check stored configuration and proposed changes with `POST /projects/{projectId}/apps/{appId}/placement`. These are read operations despite using POST and require `apps:read`. They report current capacity, hibernated capacity, provisioning possibilities and sampled rejection reasons; they do not reserve capacity.

`POST /projects/{projectId}/apps/{appId}/move` takes `targetProjectId` and requires `apps:admin`. Both projects must belong to the same organization. The caller must be an admin or the app’s creator and be allowed to edit the destination project. Use the returned destination project ID for later requests.

## Creation outcomes

| `start.state` | Meaning                                        | Next action                                                  |
| ------------- | ---------------------------------------------- | ------------------------------------------------------------ |
| `requested`   | Start accepted                                 | Poll app status                                              |
| `deferred`    | Capacity is being acquired first               | Inspect provisioning and poll status                         |
| `building`    | Repository image is being built                | Poll the returned build ID                                   |
| `failed`      | The app exists, but its automatic start failed | Read the error, correct the cause and start the existing app |

An HTTP success is not a readiness signal. Use the status resource and its returned endpoints to decide when traffic can reach the app.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.kinesis.network/api/app-configuration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.