---
sidebar_position: 4
title: 4. Deploy to cloud
pagination_prev: get-started/run-locally
pagination_next: get-started/trigger-and-logs
---

# Ship an agent to Zibby Cloud

```bash
zibby agent deploy my-agent
```

If you have multiple projects, the CLI prompts you to pick one. On success it prints a UUID:

```
✔ Deployed my-agent (v1)
✔ Bundle ready (78s) — runtime npm install eliminated

  UUID:        2b1ea07f-3ede-4bfd-a51d-431f0bab008e

  Next steps:
    zibby agent run my-agent         Run locally
    zibby agent trigger 2b1ea07f-...    Run in cloud
    zibby agent list                    View all agents
```

The UUID is **canonical** — it never changes once issued. All cloud commands (`trigger`, `logs`, `download`, `delete`) take that UUID as their identifier. The CLI caches it in `.zibby/workflows/my-agent/.zibby-deploy.json` so you don't have to remember it. Commit that file to git; collaborators share the same canonical reference.

## What deploy actually does

Two phases:

1. **Source upload** — your agent folder (sources only, no `node_modules`) is uploaded as a JSON payload to S3 via a presigned URL. The CLI also resolves your `.zibby.config.mjs` (if present at project root) and ships it inside the bundle as `zibby.config.json`, so the cloud sees the same config as your local runs.
2. **Bundle build (Heroku-style)** — a CodeBuild job downloads the sources, runs `npm install --omit=dev`, packages the result as a tarball, and uploads it to S3. The tarball is what each cloud execution downloads at trigger time, so there's **no `npm install` at runtime** — agents boot in seconds.

You'll see a live spinner with the active build step:

```
⠹ Building bundle on Zibby Cloud... [3/4] Installing dependencies — 32s
```

Pass `--verbose` if you want to see raw CodeBuild logs.

## Re-deploys keep the same UUID

Once an agent has a UUID, every subsequent `deploy` increments the version but keeps the UUID stable:

```
v1 → v2 → v3 → ...    (same UUID, same trigger URL)
```

So your `curl` calls and CI integrations don't break across deploys.

## Naming vs. UUIDs

A clean mental model:

- **Agent folder name** (`my-agent`) is *local* — used by `agent new`, `start`, `deploy`. It's just a directory name.
- **UUID** (`2b1ea07f-...`) is *canonical* — used by `trigger`, `logs`, `download`, `delete`. Stable across deploys.

`agent list` shows both:

```
┌─────────────────────────────────────┬──────────────┬──────────┬─────┐
│ UUID                                │ Name         │ Project  │ Ver │
├─────────────────────────────────────┼──────────────┼──────────┼─────┤
│ 2b1ea07f-3ede-4bfd-a51d-431f0bab008e│ my-agent  │ Zibby UI │ 3   │
│ -                                   │ scratchpad   │ -        │ -   │
└─────────────────────────────────────┴──────────────┴──────────┴─────┘
```

`-` in the UUID column means a local-only agent that hasn't been deployed yet.

→ Next: [Trigger & tail logs](./trigger-and-logs)