> ## Documentation Index
> Fetch the complete documentation index at: https://developer.upsun.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Started with Upsun Cloud

> Deploy your first project in minutes.

Upsun Cloud is a cloud hosting platform that builds, deploys, and scales your applications automatically. This guide walks you through deploying your first project—from installing the CLI to seeing your app live in production. The entire process takes about 10-15 minutes.

## Before you begin

You need:

* An Upsun account ([sign up for free](https://console.upsun.com/))
* A supported runtime (Node.js, PHP, Python, Go, Java, Ruby, or .NET)
* Git installed locally
* Basic command-line familiarity

## Choose your path

Pick the situation that matches yours and we'll take you straight to the right guide.

> [card] [Start from zero](https://developer.upsun.com/docs/get-started/here/setup.md)
>
> No project yet? Install the CLI, spin up a new project, and deploy your first app.

> [card] [Bring your project](https://developer.upsun.com/docs/get-started/here/create-project.md)
>
> Got an app? Add one YAML file to your repo, push to Upsun Cloud, and you're live.

> [card] [Connect your repo](https://developer.upsun.com/docs/get-started/here/third-party.md)
>
> Already on GitHub? Link GitHub, GitLab, or Bitbucket. Every PR auto-deploys to a live preview.

> [card] [Deploy AI & agents](https://developer.upsun.com/docs/get-started/ai/aiagent.md)
>
> Building with AI? Deploy AI agents, LLM-powered apps, or MCP servers.

## Get started quickly

The steps below follow the **"Start from zero"** path—creating a new project from scratch and deploying it to Upsun Cloud. If you already have an existing application or want to connect a Git repository, choose the appropriate card above instead.

Follow these steps to go from zero to a live Upsun Cloud deployment as fast as possible.

### 1. Install the Upsun Cloud CLI

Install the CLI for your operating system.

> [tab] macOS
>
> ```bash theme={null}
> brew install upsun/tap/upsun-cli
> ```

> [tab] Linux / WSL
>
> ```bash theme={null}
> curl -fsSL https://raw.githubusercontent.com/upsun/cli/main/installer.sh | bash
> ```

> [tab] Windows
>
> ```bash theme={null}
> scoop bucket add upsun https://github.com/upsun/homebrew-tap.git
> scoop install upsun
> ```

Then log in to your Upsun account:

```bash theme={null}
upsun login
```

[Full setup guide](https://developer.upsun.com/docs/get-started/here/setup.md) · [CLI reference](https://developer.upsun.com/cli.md)

### 2. Create your first project

Create a new Upsun Cloud project using the Console **(Create project → Start from scratch)** or the CLI:

```bash theme={null}
upsun project:create
```

[Full guide](https://developer.upsun.com/docs/get-started/here/create-project.md) · [Open Console ↗](https://console.upsun.com/projects/create-project)

### 3. Add your config file

Run `upsun init` to generate `.upsun/config.yaml`, which defines your app's runtime, services, and routes.

If your project uses services (such as a database or caching service), `upsun init` also generates an executable `.environment` script. See the full guide below for details.

> [tab] Node.js
>
> ```yaml .upsun/config.yaml theme={null}
> applications:
>   myapp:
>     type: 'nodejs:22'
>     hooks:
>       build: 'npm install && npm run build'
>
> services:
>   db:
>     type: 'postgresql:16'
>
> routes:
>   'https://{default}/':
>     type: upstream
>     upstream: 'myapp:http'
> ```

> [tab] PHP
>
> ```yaml .upsun/config.yaml theme={null}
> applications:
>   myapp:
>     type: 'php:8.3'
>     hooks:
>       build: 'composer install'
>
> services:
>   db:
>     type: 'mariadb:11.4'
>
> routes:
>   'https://{default}/':
>     type: upstream
>     upstream: 'myapp:http'
> ```

> [tab] Python
>
> ```yaml .upsun/config.yaml theme={null}
> applications:
>   myapp:
>     type: 'python:3.12'
>     hooks:
>       build: 'pip install -r requirements.txt'
>
> services:
>   db:
>     type: 'postgresql:16'
>
> routes:
>   'https://{default}/':
>     type: upstream
>     upstream: 'myapp:http'
> ```

[Full guide](https://developer.upsun.com/docs/get-started/here/configure) · [Node.js](https://developer.upsun.com/docs/get-started/here/configure/nodejs.md) · [PHP](https://developer.upsun.com/docs/get-started/here/configure/php.md) · [Python](https://developer.upsun.com/docs/get-started/here/configure/python.md)

### 4. Set CPU, RAM & disk

Configure resources for your app with `upsun resources:set`:

```bash theme={null}
upsun resources:set --size myapp:1
```

[Full guide](https://developer.upsun.com/docs/get-started/here/set-resources.md) · [Resource docs](https://developer.upsun.com/docs/manage-resources/adjust-resources.md)

### 5. Push and go live

Commit your configuration and push to deploy:

```bash theme={null}
git add .upsun/config.yaml
git commit -m "Add Upsun Cloud configuration"
upsun push
```

[Full guide](https://developer.upsun.com/docs/get-started/here/make-changes.md)

### 6. Develop locally

Open a tunnel to connect your local environment to live Upsun Cloud services:

```bash theme={null}
upsun tunnel:open
npm run dev
```

[Full guide](https://developer.upsun.com/docs/get-started/here/local) · [Tethered setup](https://developer.upsun.com/docs/development/local/tethered.md)

### 7. Connect your Git provider (optional)

**Optional:** Link [GitHub](https://developer.upsun.com/docs/integrations/source/github.md), [GitLab](https://developer.upsun.com/docs/integrations/source/gitlab.md), or [Bitbucket](https://developer.upsun.com/docs/integrations/source/bitbucket.md) to mirror, build, and auto-deploy on every push:

```bash theme={null}
upsun integration:add --type github --repository myorg/myapp
```

This step is optional—you can continue using `upsun push` directly. Source integrations are recommended for team workflows and CI/CD automation.

[Full guide](https://developer.upsun.com/docs/get-started/here/third-party.md)

## What's next

Now that you have a live deployment, explore these key topics to make the most of Upsun Cloud:

> [card] [Manage environments](https://developer.upsun.com/docs/environments.md)
>
> Create branches, preview environments, and manage your development workflow.

> [card] [Scale resources](https://developer.upsun.com/docs/manage-resources.md)
>
> Adjust CPU, RAM, and disk allocation to match your application's needs.

> [card] [Add a custom domain](https://developer.upsun.com/docs/domains)
>
> Configure your production domain and SSL certificates.

> [card] [Monitor & debug](https://developer.upsun.com/docs/observability.md)
>
> View logs, metrics, and application performance data.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.