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

# Launch

The `agent launch` command deploys your agent to Novita Sandbox. It reads the project configuration produced by `agent configure`, builds the agent template, and deploys it, reporting the resulting agent, template, and build identifiers. Run it from your project root.

## Prerequisites

* Set the `NOVITA_API_KEY` environment variable.
* A configured project — run `agent configure` first so the configuration file and Dockerfile exist.

## Usage

```bash CLI icon="terminal" theme={"system"}
novita-sandbox-cli agent launch [options]
```

```bash CLI icon="terminal" theme={"system"}
# Deploy using the project configuration
novita-sandbox-cli agent launch

# Validate everything without deploying
novita-sandbox-cli agent launch --dry-run

# Update the existing template instead of creating a new one
novita-sandbox-cli agent launch --update-existing
```

## Options

| Option                | Description                                                                            |
| --------------------- | -------------------------------------------------------------------------------------- |
| `--timeout <seconds>` | Deployment timeout in seconds. Default: `300`.                                         |
| `--no-cache`          | Disable the build cache and rebuild from scratch.                                      |
| `--dry-run`           | Perform a dry run — validate the project and configuration without actually deploying. |
| `--update-existing`   | Update the existing template instead of creating a new one.                            |
| `--verbose`           | Verbose output.                                                                        |

## What it does

When you run `agent launch`, the CLI performs the deployment in sequence:

* Checks prerequisites — the configuration file and Dockerfile must exist.
* Loads and validates the agent configuration.
* Verifies the `NOVITA_API_KEY` and checks service health.
* Builds the agent template and deploys it (unless `--dry-run` is set).

## Output

On success, the CLI reports the deployment identifiers and status:

```text Output icon="code" theme={"system"}
🎉 Agent deployment completed successfully! 🎉
Agent ID: <agent-id>
Template ID: <template-id>
Build ID: <build-id>
Status: <status>
```

<Note>
  With `--dry-run`, no template is built or deployed. The command validates the project and configuration and reports a dry-run result, so you can confirm everything is in order before a real deployment.
</Note>