> ## Documentation Index
> Fetch the complete documentation index at: https://docs.os.meetluno.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy a project

> Deploy everything or only specific modules.

When you deploy your project to Luno OS, the platform builds a new runtime from that code, promotes it, and makes the project's agents, workflows, and triggers available in the cloud.

Luno OS is deploy-first: edit `src/`, deploy, then run and inspect what's deployed. Deploy often — a full deploy ships everything, or `--filter` redeploys a single module fast.

## Where your project lives

Every Luno OS Cloud project gets a managed Git repository with two branches. `main` holds the deployed, live state. `luno/draft` is the shared work-in-progress draft — `luno deploy` publishes local edits through it, and [Luno Builder](https://docs.os.meetluno.ai/build-with-ai/platform-agent.md) sessions in the web app edit it directly. `luno pull` fetches and merges the shared draft by default (pass `--published` for the exact revision of the active deploy). Clients never push to managed `main` — deploy promotes the draft for you.

> [!NOTE]
>
> **Self-hosting:** a self-hosted platform provisions the same `main` + `luno/draft` layout. By default it uses bare repositories on the platform's disk (`LUNO_GIT_ROOT`, default `~/.luno/git`) served read-only over smart HTTP at `<platform-url>/git`; set the `PROJECT_GIT_GITHUB_*` variables to use a GitHub App instead. Local repositories support fetch and clone only; pushes always go through deploy.

Deploying is `luno deploy` pointed at a specific project. For anything shared or production-facing, deploy often, and use `luno pull` to pick up teammates' and platform-agent draft edits.

## Before you deploy

You need:

* A Luno OS account and organization
* A project in that organization
* A codebase created with `luno init`
* Any cloud credentials your agents or workflows need

```bash theme={null}
luno auth login
luno projects list
```

> [!NOTE]
>
> `luno auth login` is for local setups only. Hosted sessions — the in-app [Luno Builder](https://docs.os.meetluno.ai/build-with-ai/platform-agent.md) and [MCP](https://docs.os.meetluno.ai/build-with-ai/mcp-for-agents.md) workspaces — already have credentials injected and must never run it.

If you do not have a project yet, create one:

```bash theme={null}
luno projects create --name "Support automations"
```

## Full deploy

Run a full deploy the first time you deploy to a project. Link the directory first (or pass `--project` for a one-off deploy):

```bash theme={null}
luno projects link --project support-automations
luno deploy
```

`luno deploy` compares the pinned managed-Git commits locally, builds the accepted candidate, uploads it, and waits for a healthy platform activation. Snapshot-only projects also lint, typecheck, build, and upload. You do not need to run `luno build`, `luno lint`, or `luno typecheck` first.

A managed full deploy:

1. Pins `main` (M0) and draft (D0)
2. Composes the full draft delta onto an ephemeral candidate
3. Builds and uploads the candidate locally, then health-checks it on the platform
4. Fast-forwards `main` after health, then promotes the artifact

If the draft already matches main, deploy exits as a no-op.

After a successful deploy, runtime commands target your linked cloud project. Project targeting comes from `project` and `organization` in `luno.config.ts` (set by `luno projects link`). See [project targeting](https://docs.os.meetluno.ai/cli.md#project-targeting).

## Deploy from another directory

Use `--dir` when your current shell is not inside the project codebase:

```bash theme={null}
luno deploy --dir ./apps/support-automations --project support-automations
```

When the directory is linked via `luno projects link`, you can omit `--project`.

The directory you deploy is the codebase that will define the platform project. Make sure it is the same tree you have been editing.

## Verify a deploy

After deploy, check the deployment history and run something against the project:

```bash theme={null}
luno projects deployments list --project support-automations
luno --project support-automations workflow run greeting --input '{"name":"Ada"}'
```

You can also inspect the project in the web app and review [run history](https://docs.os.meetluno.ai/learn/logs/overview.md) after agents or workflows run.

## Pull the draft or the published revision

`luno pull` fetches the shared draft (`luno/draft`) and merges it into your local checkout, then installs dependencies. Use it to pick up teammates' and platform-agent edits, bootstrap an empty directory, or resolve conflicts after a failed deploy merge.

```bash theme={null}
luno pull --project support-automations            # shared draft, into the current directory
luno pull --project support-automations --dir ./support-automations
luno pull --project support-automations --published # active deploy revision instead
```

Pass `--published` to pull the active published artifact revision instead. That revision is the exact commit recorded on the active deploy — it may intentionally differ from current managed `main` while promotion or reconciliation is in flight.

An empty directory is initialized at the pulled commit. A non-empty non-Git directory is refused. If the merge conflicts, Git leaves conflict markers in place — resolve them, commit, and deploy again. Legacy snapshot-only artifacts still pull via the bulk source download.

## Deploy only specific modules

After a project has an active full deploy, use `--filter` to redeploy one or more modules. Managed-Git deploys analyze dependency impact locally and prompt before expanded or unknown impact; pass `--accept-impact` in non-interactive environments.

```bash theme={null}
luno deploy --filter agents/support
luno deploy --filter workflows/morning-check
```

Filters match build entry keys such as `agents/support`, `workflows/morning-check`, or `triggers/incoming-message`. They are exact matches, not globs.

See [Deploy individual files](https://docs.os.meetluno.ai/learn/projects/deploy-individual-files.md) for details.

## Common mistakes

| Mistake | What to do instead |
| - | - |
| Deploy merge conflicts | Run `luno pull`, resolve, commit, then deploy again |
| Dirty or uncommitted checkout | Commit your changes before `luno deploy` |
| Running `--filter` on the first deploy | Run a full deploy first |
| Deploying from the wrong directory | Pass `--dir` or change into the project codebase |
| Expecting `.env` to upload | Set credentials on the cloud project |

## Next steps

> **[Manage projects](https://docs.os.meetluno.ai/learn/projects/manage-projects.md)**
>
> Create projects and invite teammates before you deploy.

> **[Deploy individual files](https://docs.os.meetluno.ai/learn/projects/deploy-individual-files.md)**
>
> Redeploy a targeted module or keep work-in-progress code out of production.

> **[CLI reference](https://docs.os.meetluno.ai/cli.md#deploy)**
>
> See the full deploy command reference.

> **[Run history](https://docs.os.meetluno.ai/learn/logs/overview.md)**
>
> Inspect what happens after your deployed agents and workflows run.


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