---
title: "Stagely docs: pull request previews in your own cloud"
description: "Stagely gives any GitHub pull request a stagelet, a private running copy of your app in your own cloud account. Find the path for your part of the work."
url: https://stagely.dev/docs
---

## Pick your path

| You are                                     | You want to                                                               | Start with                             |
| ------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------- |
| The person who sets Stagely up for the team | Connect GitHub and your cloud account, and get the first stagelet running | [Quickstart](https://stagely.dev/docs/setup.md)              |
| A developer on the team                     | Describe your app in `.stagely.yml`, and deploy pull requests             | [.stagely.yml](https://stagely.dev/docs/app/stagely-yml.md)  |
| Someone who runs coding agents              | Let an agent deploy and test the pull requests it opens                   | [Connect a coding agent](https://stagely.dev/docs/agents.md) |
| A reviewer                                  | Open a pull request's stagelet and check the change                       | [Review a stagelet](https://stagely.dev/docs/review.md)      |

Your team sets up Stagely only once, and the first path covers most of that setup. If nobody on your team has set up Stagely yet, start with the [Quickstart](https://stagely.dev/docs/setup.md).

## How the parts fit

Stagely plans each deploy. Two programs in your cloud account do the work.

| Part              | Runs in                         | Does                                                                                                                                                                                                                |
| ----------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Stagely           | Stagely's cloud                 | Serves the console, the API and the MCP endpoint. Plans each deploy, keeps the record of every deploy, and gives passes into stagelets. Never holds your cloud credentials or secret values.                        |
| `stagely-agent`   | Your cloud, on the agent host   | Holds your cloud credentials and secret values. Creates machines, builds images and runs stagelets. Accepts no inbound connections from Stagely.                                                                    |
| `stagely-gateway` | Your cloud, on the gateway host | The only part that accepts internet traffic. Serves each stagelet's private URL to people who have a pass. Holds no cloud credentials or secret values: it keeps only its own Stagely key and its TLS certificates. |
| `stagely`         | Your computer                   | The setup CLI. Prepares an environment in your cloud account and enrolls the agent and the gateway.                                                                                                                 |

The agent and the gateway each open a WebSocket connection to Stagely. Your cloud account needs no inbound port from Stagely.

## Words in these docs

| Word        | Meaning                                                                                                                                                   |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Stagelet    | The running copy of one pull request: its own VM, its private URL and its history of deploys                                                              |
| Environment | A Stagely environment, with one agent and one gateway, that `stagely setup` prepared in a cloud account. One cloud account can hold several environments. |
| Project     | A GitHub repository bound to an environment, with its settings and config                                                                                 |
| Operation   | One deploy, reset or delete of a stagelet, with its steps and log                                                                                         |
| Revision    | The inputs and results of one deploy: the commit, the config and the image digests                                                                        |