# tanomis agent deploy

Reference for tanomis agent deploy: package, upload, and remotely build an agent from local source.

Generated from the <code>tanomis</code> command tree on 2026-10-01. Flags and defaults match the binary; run <code>tanomis agent deploy --help</code> for the version you have installed.

## Usage

```text title="Usage"
tanomis agent deploy [PATH] [flags]
```

## Description

Turn local Python agent source into a remote build (feature 260703d1d).

Preflights PATH (default "."): parses agent.yaml, requires a harness (framework),
rejects a stray Dockerfile or an unsupported top-level build field, and flags
secret-looking files (.env, *.pem, *.key, or a name containing "credentials") — those
are excluded from the package as well as warned about. Packages PATH deterministically
(a repackage of the same tree yields an identical checksum), enforces the Python lock
policy (a remote build requires a uv.lock or a pinned requirements.txt; a bare
pyproject.toml is rejected), then creates a build job, uploads the bundle, and streams
its progress to the terminal.

`--dry-run` stops after packaging and prints the plan: no build is created and no bytes
are uploaded. Public egress additionally performs an authenticated read-only ceiling validation.

`--stage` builds and registers the version, ready to start sessions, and enables it for
nobody: the tenant keeps the version it serves. Test it with `tanomis eval ci`, then
release it with `tanomis agent promote`, naming the version and the tenant.

## Flags

| Flag | Type | Description |
|---|---|---|
| `--allow-unlocked` | bool | Not supported for a remote build: the build service requires a uv.lock or a pinned requirements.txt (using this flag now returns a clear error rather than failing the remote build). |
| `--build-profile` | string | Build profile (only python-managed is supported in v1). Default `python-managed`. |
| `--dry-run` | bool | Preflight and package without creating a build or uploading source; public egress validates the ceiling. |
| `--force-rebuild` | bool | Reserved for a future server-side build cache; currently a no-op. |
| `--name` | string | Agent name (default: agent.yaml's name). |
| `--no-stream-logs` | bool | Disable streaming build events (poll for terminal status instead). |
| `--no-wait` | bool | Return immediately after the source uploads, without waiting for the build. |
| `--scope` | string | Registration scope: organization, workspace or platform (default: organization where the platform enables it, else workspace). |
| `--stage` | bool | Build and register the version without enabling it for the tenant (test it before release). |
| `--stream-logs` | bool | Stream build events to the terminal (default: on when stdout is a terminal). Default `true`. |
| `--tenants` | string | Platform deployment targets: all or a comma-separated tenant list (requires `--scope` platform). |
| `--version` | string | Version label (default: agent.yaml's version). |
| `--wait` | bool | Wait for the build to reach a terminal status before exiting. Default `true`. |

<details>
<summary>Global flags</summary>

| Flag | Type | Description |
|---|---|---|
| `--config` | string | Config file path. |
| `--context` | string | Config context to use. |
| `-o`, `--output` | string | Output format: table\|json. |
| `--tenant` | string | Tenant id (X-Tenant-ID). |
| `--verbose` | bool | Verbose output. |

</details>

## Examples