Skip to main content
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 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.
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
luno auth login is for local setups only. Hosted sessions — the in-app Luno Builder and MCP workspaces — already have credentials injected and must never run it.
If you do not have a project yet, create one:

​
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):
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.

​
Deploy from another directory

Use --dir when your current shell is not inside the project codebase:
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:
You can also inspect the project in the web app and review run history 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.
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.
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 for details.

​
Common mistakes

​
Next steps

Manage projects

Create projects and invite teammates before you deploy.

Deploy individual files

Redeploy a targeted module or keep work-in-progress code out of production.

CLI reference

See the full deploy command reference.

Run history

Inspect what happens after your deployed agents and workflows run.