## 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](/docs/quickstart) to install the Guava CLI.

#### Step 2 — Log in

<CodeBlock code="guava login" filename="terminal" language="bash" />

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

<CodeBlock code="guava create my-agent" filename="terminal" language="bash" />

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:

<CodeBlock
  filename="terminal"
  language="bash"
  code={`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`}
/>

#### 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:

<CodeBlock code="guava deploy up" filename="terminal" language="bash" />

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

<CodeBlock code="guava deploy up" filename="terminal" language="bash" />

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:

<CodeBlock code="guava deploy up --rebuild" filename="terminal" language="bash" />

If a deployment is already running, the CLI will ask whether to reuse or replace it.

#### Step 6 — Check deployment status

<CodeBlock code="guava deploy status" filename="terminal" language="bash" />

Shows whether your deployment is starting up, running, or has encountered an error.

#### Step 7 — View logs

<CodeBlock
  filename="terminal"
  language="bash"
  code={`# 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

<CodeBlock code="guava deploy ls" filename="terminal" language="bash" />

Prints a table with columns: NAME, NUMBER, ACTIVE, ID.

#### Step 9 — Update project configuration

<CodeBlock code="guava deploy update" filename="terminal" language="bash" />

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

#### Step 10 — Check for code changes

<CodeBlock code="guava deploy changed" filename="terminal" language="bash" />

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

#### Step 11 — Tear down

<CodeBlock code="guava deploy down" filename="terminal" language="bash" />

Stops the running sandbox. You can also target a specific task:

<CodeBlock code={`guava deploy down --id <task-id>`} filename="terminal" language="bash" />

### Phone number management

Buy a phone number for your project at any time:

<CodeBlock code="guava numbers buy" filename="terminal" language="bash" />

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 <code>/tmp</code>. Note that <code>/tmp</code> is ephemeral: contents are lost when the sandbox restarts.

### Quick reference

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