> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-for-developers/key-concepts/hosting-your-application.md). # Hosted Apps Let CARTO host and serve your application behind your organization's login {% hint style="info" %} **Private Preview:** Hosted Apps is available to selected accounts during its Private Preview. To request access, contact your CARTO representative. {% endhint %} ## Introduction As we've seen in previous concepts, most applications built with CARTO are static frontends: HTML, JavaScript and CSS files that call the CARTO APIs directly from the browser. Once built, they still need a place to be served from and, if they are private, a login for their users. With **Hosted Apps**, CARTO hosts the application for you. You deploy the built files with the [CARTO CLI](/carto-for-agents/cli.md), and CARTO serves them at a URL behind your organization's login: * **Users sign in with CARTO**, including your [Single Sign-On (SSO)](/carto-user-manual/settings/sso.md) when it is configured. There is no OAuth client to create and no login code to write. * **The application runs as the signed-in user.** It receives that person's own access token, so it can only see and do what they can see and do in CARTO. * **Sharing works like it does for maps and workflows:** keep the application private, or [share it](/carto-for-developers/reference/hosted-apps/runtime-and-authentication.md#sharing) with your whole organization or with specific groups and users. * **Every deploy is a new version**, and you can [roll back](/carto-for-developers/reference/hosted-apps/runtime-and-authentication.md#versions) to a previous one at any time. Anything you can build with CARTO for Developers can be hosted this way, from a single map to a complete analytical application. ## How it works 1. **You build your application** with deck.gl and `@carto/api-client`, as you would for any other CARTO application, and deploy the built files with [`carto app deploy`](/carto-for-agents/cli/command-reference/app.md). The files must follow a few [bundle requirements](/carto-for-developers/reference/hosted-apps/bundle-requirements-and-limits.md), such as relative asset paths. 2. **A user opens the application URL.** CARTO checks that they are signed in and that the application is shared with them, and then serves the files. 3. **The application reads the user's credentials** from `carto-info.json`, a small file that CARTO serves next to the application for each user. It contains the user's access token and the API base URL, which the application uses with the CARTO APIs. See the [`carto-info.json` contract](/carto-for-developers/reference/hosted-apps/runtime-and-authentication.md). 4. **Optionally, the application declares** [**Named Sources**](/carto-for-developers/guides/avoid-exposing-sql-queries-with-named-sources.md) in a [`carto.json` manifest](/carto-for-developers/reference/hosted-apps/app-manifest.md). CARTO registers them when you deploy, and the application runs its queries by name, so no SQL reaches the browser. {% hint style="success" %} **We recommend Hosted Apps when:** your application is meant for people in your CARTO organization, and you would rather not set up hosting and a login for it. {% endhint %} ## Hosted Apps and authentication A hosted application does not use any of the [authentication methods](/carto-for-developers/key-concepts/authentication-methods.md) directly. CARTO signs the user in and hands the application an ordinary [OAuth Access Token](/carto-for-developers/key-concepts/authentication-methods/oauth-access-tokens.md) that belongs to that user. Compared to a [private application](/carto-for-developers/guides/build-a-private-application.md), the token is the same; what changes is that CARTO takes care of the login, so your code only has to read it. The [runtime and authentication reference](/carto-for-developers/reference/hosted-apps/runtime-and-authentication.md) describes the session and how to renew it. ## Choosing where to host your application | | Builder map | Hosted application | Your own hosting | | ------------------ | ----------------------------------- | ----------------------------- | ---------------------------------------------------- | | Who can open it | CARTO users, or anyone if published | CARTO users you share it with | Anyone you allow, including the public | | Login | Handled by CARTO | Handled by CARTO | Yours to implement, or an API Access Token if public | | Interface | Builder's layout and components | Your own | Your own | | Where it is served | CARTO | CARTO, under `/app//` | Your infrastructure | Use a **Builder map** when its layout, styling and widgets already cover what you need. Use a **hosted application** when you need your own interface and the audience is inside your CARTO organization. **Host it yourself** when the application must be public, needs a backend of its own, or has to live on your own domain. For a public application, follow [Build a public application](/carto-for-developers/guides/build-a-public-application.md); [`carto app package`](/carto-for-agents/cli/command-reference/app.md) can prepare that public version from the same files. ## Things to keep in mind * **Users need a CARTO login in your organization.** Hosted applications cannot be public. * **Only static files are served.** There is no server-side code. See [Bundle requirements and limits](/carto-for-developers/reference/hosted-apps/bundle-requirements-and-limits.md). * **The application can only load resources and call APIs from CARTO and a short list of allowed origins**, set by its [Content Security Policy](/carto-for-developers/reference/hosted-apps/bundle-requirements-and-limits.md#the-content-security-policy). * **Hosted applications cannot be embedded** in other websites. The complete list is in [Limitations](/carto-for-developers/reference/hosted-apps/limitations.md). {% hint style="success" %} **Learn more** * [Hosting your first application](/carto-for-developers/quickstart/hosting-your-first-application.md) deploys a one-file application in a few minutes. * [Hosting your application in CARTO](/carto-for-developers/guides/build-a-hosted-application.md) walks you through building, deploying and sharing a complete application. * The [Hosted Apps reference](/carto-for-developers/reference/hosted-apps.md) describes the `carto.json` manifest, the runtime and authentication contract, and the bundle requirements and limits. {% endhint %} --- # 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.carto.com/carto-for-developers/key-concepts/hosting-your-application.md?ask=&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.