> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/references/interfaces/apps.md).

# Apps

Choose between an App, which DataOS deploys and runs, and a Link, which registers an existing external URL in the catalog.

DataOS provides two resource types for making experiences discoverable through the catalog and app launcher:

* **App:** DataOS deploys and operates a containerized application.
* **Link:** DataOS registers an existing external URL. It does not deploy anything.

## Choose App or Link

| Question                                             | App                              | Link                                        |
| ---------------------------------------------------- | -------------------------------- | ------------------------------------------- |
| Does DataOS run a container?                         | Yes                              | No                                          |
| Does it create a Service?                            | Yes                              | No                                          |
| Can it provide ingress, OIDC, CORS, and rate limits? | Yes                              | No                                          |
| Does it create a catalog entry?                      | Yes                              | Yes                                         |
| Open target                                          | Path on the DataOS host          | Full external URL                           |
| Typical examples                                     | Streamlit, Flask, Next.js, Nginx | Superset, Grafana, wiki, external dashboard |

Use an **App** when the workload needs compute, runtime configuration, secrets, networking, scaling, metrics, storage, or platform security controls.

Use a **Link** when the destination already exists and users only need a governed catalog shortcut.

## How an App works

An App has three layers:

1. **Placement:** compute cluster, runtime identity, replicas, CPU, and memory.
2. **Runtime:** image, command, port, environment, secrets, HTTP, storage, metrics, and scaling.
3. **Catalog:** description, owners, tags, references, visibility, and Open action.

Applying an App validates the manifest, creates its integrated Service, plans the workload, configures routing, and then registers the App in the catalog.

## How a Link works

A Link stores metadata and an external URL in the catalog. The destination remains responsible for hosting, TLS, authentication, authorization, and availability.

## Common workflow

The App and Link domain definitions are normally installed once by a platform administrator:

```bash
dataos-ctl domain apply -f app-domain-definition.yaml
dataos-ctl domain apply -f link-domain-definition.yaml
```

Users then create instances:

```bash
dataos-ctl resource apply -f app.yaml
dataos-ctl resource apply -f link.yaml
```

## Important rules

* App `spec.app.link.url` is a path such as `/sales`; it is not a full URL.
* Link `spec.link.url` is a complete URL such as `https://example.com`.
* App secret IDs use `tenant:secret-name`.
* Visibility uses the scoped object: `global`, `tenants`, or `pattern`.
* Catalog visibility does not replace application authorization.
* Applications using `stripPath: false` must serve routes and assets from the configured base path.

Continue with:

* [Deploy a data application](https://v2.dataos.info/references/interfaces/apps/deploy-a-data-application.md)
* [Link an external application](https://v2.dataos.info/references/interfaces/apps/link-an-external-application.md)


---

# 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://v2.dataos.info/references/interfaces/apps.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.
