> ## 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

> Deploy your first project in minutes.

Upsun 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.

<CardGroup cols={2}>
  <Card title="Start from zero" icon="layers" color="#6046ff" href="/docs/get-started/here/setup">
    No project yet? Install the CLI, spin up a new project, and deploy your first app.
  </Card>

  <Card title="Bring your project" icon="folder-open" color="#6046ff" href="/docs/get-started/here/create-project">
    Got an app? Add one YAML file to your repo, push to Upsun, and you're live.
  </Card>

  <Card title="Connect your repo" icon="git-branch" color="#6046ff" href="/docs/get-started/here/third-party">
    Already on GitHub? Link GitHub, GitLab, or Bitbucket. Every PR auto-deploys to a live preview.
  </Card>

  <Card title="Deploy AI & agents" icon="bot" color="#6046ff" href="/docs/get-started/ai/aiagent">
    Building with AI? Deploy AI agents, LLM-powered apps, or MCP servers.
  </Card>
</CardGroup>

## Get started quickly

The steps below follow the **"Start from zero"** path—creating a new project from scratch and deploying it to Upsun. 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 deployment as fast as possible.

<Steps titleSize="h3">
  <Step title="Install the Upsun CLI" id="install-cli">
    Install the CLI for your operating system.

    <Tabs>
      <Tab title="macOS">
        ```bash theme={null}
        brew install upsun/tap/upsun-cli
        ```
      </Tab>

      <Tab title="Linux / WSL">
        ```bash theme={null}
        curl -fsSL https://raw.githubusercontent.com/upsun/cli/main/installer.sh | bash
        ```
      </Tab>

      <Tab title="Windows">
        ```bash theme={null}
        scoop bucket add upsun https://github.com/upsun/homebrew-tap.git
        scoop install upsun
        ```
      </Tab>
    </Tabs>

    <div style={{marginTop: '-0.5rem'}}>
      Then log in to your Upsun account:

      ```bash theme={null}
      upsun login
      ```
    </div>

    [Full setup guide](/docs/get-started/here/setup) · [CLI reference](/cli)

    <div style={{marginBottom: '1.5rem'}} />
  </Step>

  <Step title="Create your first project" id="create-project">
    Create a new Upsun project using the Console **(Create project → Start from scratch)** or the CLI:

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

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

    <div style={{marginBottom: '1.5rem'}} />
  </Step>

  <Step title="Add your config file" id="add-config">
    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.

    <Tabs>
      <Tab title="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>

      <Tab title="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>

      <Tab title="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'
        ```
      </Tab>
    </Tabs>

    [Full guide](/docs/get-started/here/configure) · [Node.js](/docs/get-started/here/configure/nodejs) · [PHP](/docs/get-started/here/configure/php) · [Python](/docs/get-started/here/configure/python)

    <div style={{marginBottom: '1.5rem'}} />
  </Step>

  <Step title="Set CPU, RAM & disk" id="set-resources">
    Configure resources for your app with `upsun resources:set`:

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

    [Full guide](/docs/get-started/here/set-resources) · [Resource docs](/docs/manage-resources/adjust-resources)

    <div style={{marginBottom: '1.5rem'}} />
  </Step>

  <Step title="Push and go live" id="push-and-go-live">
    Commit your configuration and push to deploy:

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

    [Full guide](/docs/get-started/here/make-changes)

    <div style={{marginBottom: '1.5rem'}} />
  </Step>

  <Step title="Develop locally" id="develop-locally">
    Open a tunnel to connect your local environment to live Upsun services:

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

    [Full guide](/docs/get-started/here/local) · [Tethered setup](/docs/development/local/tethered)

    <div style={{marginBottom: '1.5rem'}} />
  </Step>

  <Step title="Connect your Git provider (optional)" id="connect-git">
    **Optional:** Link [GitHub](/docs/integrations/source/github), [GitLab](/docs/integrations/source/gitlab), or [Bitbucket](/docs/integrations/source/bitbucket) 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](/docs/get-started/here/third-party)

    <div style={{marginBottom: '1.5rem'}} />
  </Step>
</Steps>

## What's next

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

<CardGroup cols={2}>
  <Card title="Manage environments" icon="code-branch" color="#6046ff" href="/docs/environments">
    Create branches, preview environments, and manage your development workflow.
  </Card>

  <Card title="Scale resources" icon="gauge-high" color="#6046ff" href="/docs/manage-resources">
    Adjust CPU, RAM, and disk allocation to match your application's needs.
  </Card>

  <Card title="Add a custom domain" icon="globe" color="#6046ff" href="/docs/domains">
    Configure your production domain and SSL certificates.
  </Card>

  <Card title="Monitor & debug" icon="chart-line" color="#6046ff" href="/docs/observability">
    View logs, metrics, and application performance data.
  </Card>
</CardGroup>