deployment.md
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
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
The CLI walks you through interactive configuration:
- Base image — Python version (3.10, 3.11, 3.12, 3.13, or 3.14)
- 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 |
- 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:
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
The CLI will:
- Check for changes — if your code hasn't changed since the last deploy, the build step is skipped automatically.
- Upload your code to cloud storage.
- Build a container image with your chosen Python version and dependencies. The CLI shows build progress in the terminal.
- 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:
If a deployment is already running, the CLI will ask whether to reuse or replace it.
Step 6 — Check deployment status
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
Prints a table with columns: NAME, NUMBER, ACTIVE, ID.
Step 9 — Update project configuration
Re-prompts for configuration fields (name, base image, tier) with current values shown as defaults.
Step 10 — Check for code changes
Tells you whether your code has changed since the last deploy.
Step 11 — Tear down
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:
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.