# Deploying and builds

```sh
zya deploy
```

`deploy` uploads your project's source, waits for Zenitya to build it, and
prints the result. Nothing is built on your machine. Deploying needs an owner
or admin login, or a machine key with the `deploy` scope.

## What is uploaded

Everything in the project directory except:

- hidden files and folders, such as `.env` and `.git`
- `node_modules/`, `dist/`, `build/` and `coverage/`
- files that look like credentials: `*.env`, `*.pem`, `*.key`, `*.p12`,
  `*.pfx`, SSH keys, `bunfig.toml`, and any name containing `credential`,
  `secret`, `token` or `service-account`, including source files such as
  `src/tokens.ts` (rename those)
- source maps (`*.map`) and native modules (`*.node`)

`deploy` lists what it left out. The upload must include `package.json` and
`bun.lock` (run `bun install` first) and the entrypoint. Symbolic links are
refused. Source is limited to 2,048 files and 16 MiB.

`.env` is never uploaded. Give deployed tools their configuration with
[secrets](secrets.md).

## How a build runs

| Step       | What happens                                                    |
| ---------- | --------------------------------------------------------------- |
| `skills`   | Checks the files in `skills/`, if any                           |
| `install`  | Installs the dependencies pinned in `bun.lock`                  |
| `bundle`   | Bundles your entrypoint                                         |
| `describe` | Loads the bundle and reads every tool's name, schemas and hints |

If every step passes, the build's deployment becomes the project's active one
and agents see the new tools on their next call. If any step fails, nothing
changes: the previous deployment keeps serving.

A build that has been running for a while is not lost if your terminal is: run
`zya deploy` again with the `--idempotency-key` it printed, and it resumes
waiting for the same build instead of starting another.

## Reading a failed build

```sh
zya builds list                               # recent builds and their state
zya builds view <build-id>                    # steps, timings and the error
zya builds logs <build-id>                    # everything the build printed
zya builds logs <build-id> --phase install    # one step's output
zya builds logs <build-id> --follow           # while it is still running
```

Common causes:

- **`install` fails**: `bun.lock` is out of date or missing. Run `bun install`
  and deploy again.
- **`bundle` fails**: a type or import error, often a file that was left out
  of the upload. Run `bun run check` and check the "Not uploaded" list.
- **`describe` fails**: the entrypoint threw while loading, does not
  `export default` a `Project`, or a tool's schema is invalid. Run any tool with
  `zya exec <tool> --local` to see the same error locally.

## Versions

Every build that succeeds creates a deployment. Only the newest successful one
is active; `zya builds list` shows which. To roll back, deploy the earlier
source again.