## Deployment

Guava Deploy is a managed cloud platform that lets you deploy Guava voice-agent projects without provisioning or managing your own infrastructure. When you run `guava deploy up`, the CLI packages your project, builds it in the cloud, and launches it for you. No servers to set up, no infrastructure to manage.

### Security

Your deployments are secure by default:

- Isolated environments — Each deployment runs in its own private sandbox, completely separated from other users' workloads.
- Network protection — Your sandbox can make outbound requests to the internet (e.g. calling APIs), but no one can connect into your sandbox from the outside.
- Secure credentials — Your API key and phone number are injected securely at runtime and never appear in logs.
- Dedicated resources — CPU and memory are reserved for your deployment, so performance is consistent.

### Step-by-step guide

#### Prerequisites

- A Guava account
- A terminal (macOS, Linux, or WSL on Windows)

#### Step 1 — Install the CLI

Follow the [Quickstart guide](https://goguava.ai/docs/quickstart) to install the Guava CLI.

#### Step 2 — Log in

```bash
guava login
```
This opens your browser for authentication. Once you log in, the CLI is authenticated and all subsequent commands will use your account.

#### Step 3 — Create a project

```bash
guava create my-agent
```
The CLI walks you through interactive configuration:

1. **Base image** — Python version (3.10, 3.11, 3.12, 3.13, or 3.14)
2. **Instance tier** — choose based on your workload:

| Tier            | CPU   | Memory | Use case                    |
   |----------------|-------|--------|-----------------------------|
   | `guava-seed`   | 1 core| 1Gi    | Development / testing       |
   | `guava-fruit`  | 2 cores| 2Gi   | Standard production         |
   | `guava-tree`   | 4 cores| 4Gi   | High-performance workloads   |

3. **Phone number** — optionally buy a number now (or later with `guava numbers buy`)

This generates the following project structure:

```bash
my-agent/
.guava          # Project config (project ID, tier, base image, etc.)
main.py         # Required entry point — your agent code goes here
pyproject.toml  # Python dependencies
PRD.md          # Product requirements template
README.md       # Project readme
```

Important: If you use git, the `.guava` file must be committed and kept up to date. The CLI reads it to identify your project and track deployment state.

#### Deploying an existing project

If you already have a Python project with a `main.py`, you don't need to run `guava create`. Just navigate to your project directory and run:

```bash
guava deploy up
```
The CLI will detect that there's no `.guava` config and ask if you'd like to initialize one. It will then prompt you for a base image and instance tier, generate a `.guava` file, and proceed with the deploy.

#### Step 4 — Write your agent code

Edit `main.py` with your voice-agent logic.

For dependencies, Guava supports several common Python workflows. The build system automatically detects which one you're using based on the files in your project:

| Files present                   | What happens                                          |
|---------------------------------|-----------------------------------------------------|
| `uv.lock` + `pyproject.toml`   | Installs with `uv sync --frozen` (locked, reproducible) |
| `poetry.lock` + `pyproject.toml`| Installs with `uv sync`                             |
| `pyproject.toml` (alone)       | Installs with `uv sync`                             |
| `requirements.txt`              | Installs with `uv pip install -r requirements.txt` |
| `requirements.in`               | Installs with `uv pip install -r requirements.in`  |

#### Step 5 — Deploy

```bash
guava deploy up
```

The CLI will:
1. **Check for changes** — if your code hasn't changed since the last deploy, the build step is skipped automatically.
2. **Upload your code** to cloud storage.
3. **Build a container image** with your chosen Python version and dependencies. The CLI shows build progress in the terminal.
4. **Launch your sandbox** and wait until it's running. The CLI shows the deployment status as it starts up.

To force a full rebuild even if your code hasn't changed:

```bash
guava deploy up --rebuild
```
If a deployment is already running, the CLI will ask whether to reuse or replace it.

#### Step 6 — Check deployment status

```bash
guava deploy status
```
Shows whether your deployment is starting up, running, or has encountered an error.

#### Step 7 — View logs

```bash
# Runtime logs (default: last 200 lines, max 1000)
guava deploy logs
guava deploy logs -n 500

# Build logs (returns a temporary URL to view full build output)
guava deploy build-logs
```

#### Step 8 — List all deployments

```bash
guava deploy ls
```
Prints a table with columns: NAME, NUMBER, ACTIVE, ID.

#### Step 9 — Update project configuration

```bash
guava deploy update
```
Re-prompts for configuration fields (name, base image, tier) with current values shown as defaults.

#### Step 10 — Check for code changes

```bash
guava deploy changed
```
Tells you whether your code has changed since the last deploy.

#### Step 11 — Tear down

```bash
guava deploy down
```
Stops the running sandbox. You can also target a specific task:

```bash
guava deploy down --id <task-id>
```

### Phone number management

Buy a phone number for your project at any time:

```bash
guava numbers buy
```
The CLI fetches available numbers, shows you a match, and stores the purchased number in `.guava`. On the next deploy, the number is passed to your sandbox as the `GUAVA_AGENT_NUMBER` environment variable.

### File caching

If you need to cache a file at runtime, write it to `/tmp`. Note that `/tmp` is ephemeral: contents are lost when the sandbox restarts.

### Quick reference

For a full list of commands and options, see the [CLI Reference](https://goguava.ai/docs/cli-reference).