Documentation

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 to install the Guava CLI.

Step 2 — Log in

terminal

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

terminal

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:

terminal

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:

terminal

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

terminal

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:

terminal

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

terminal

guava deploy status

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

Step 7 — View logs

terminal

# 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

terminal

guava deploy ls

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

Step 9 — Update project configuration

terminal

guava deploy update

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

Step 10 — Check for code changes

terminal

guava deploy changed

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

Step 11 — Tear down

terminal

guava deploy down

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

terminal

guava deploy down --id <task-id>

Phone number management

Buy a phone number for your project at any time:

terminal

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.

→ Next: CLI Reference

Questions? hi@goguava.ai

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

# 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