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 Windows PowerShell)

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.

If you belong to multiple organizations, run guava org use to pick the right one first — the active org determines which project, numbers, and deployments every other command sees.

Step 3 — Create a project

terminal
guava create my-agent

The CLI walks you through interactive configuration:

1. Language & base image — pick a language, then a version. The base image determines your project's runtime.

Base image versions: python-sandbox:3.14 (default), 3.13, 3.12, 3.11, 3.10.

Scaffolds main.py with a pyproject.toml manifest.

2. Instance tier — choose based on your workload:

TierCPUMemoryUse case
guava-seed1 core1GiDevelopment / testing
guava-fruit2 cores2GiStandard production
guava-tree4 cores4GiHigh-performance workloads

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

This generates the following project structure:

project structure
my-agent/
guava.toml      # Project config (project ID, tier, base image, etc.)
main.py         # Required entry point — your agent code goes here
pyproject.toml  # Python dependencies
README.md       # Project readme
guava-docs.md   # Reference docs for AI coding assistants

guava create runs uv sync to install dependencies automatically.

Projects created with CLI versions 0.29.0 and lower used a JSON .guava file instead of guava.toml. The CLI migrates them automatically the next time it writes the config (e.g. guava update or guava deploy up).

Deploying an existing project

If you already have a project with a main.py (Python) or main.ts (TypeScript), 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.toml config and ask if you'd like to initialize one. It will then prompt you for a language, base image, and instance tier, generate a guava.toml file, and proceed with the deploy.

Step 4 — Write your agent code

Edit your entry point (main.py for Python, main.ts for TypeScript) with your voice-agent logic.

Add dependencies the usual way for your language — a Python manifest/lockfile (pyproject.toml, requirements.txt, uv.lock, …) or a Node one (package.json, package-lock.json, pnpm-lock.yaml, yarn.lock). The build auto-detects them at deploy time; see dependency detection in the CLI reference for the exact install command per file.

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 base image 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, STATUS, REPLICAS, PROJECT ID.

Step 9 — Tear down

terminal
guava deploy down

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

terminal
guava deploy down --id <project-id>

Other project commands

These commands aren't part of the core deploy flow but are handy as your project evolves.

Update project configuration — re-prompts for configuration fields (name, base image, tier) with current values shown as defaults:

terminal
guava update

Check for code changes — tells you whether your code has changed since the last deploy:

terminal
guava deploy changed

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.toml.

Temporary file storage

To write files at runtime (for example, to cache data), use /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