import { CodeBlock } from '../views/docs/CodeBlock';
import { Callout, Prose, NextLink } from '../views/docs/prose';

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

<Callout>
  <ul className="space-y-2 list-none pl-0 mb-0">
    <li><span className="text-primary font-semibold">Isolated environments</span> — Each deployment runs in its own private sandbox, completely separated from other users' workloads.</li>
    <li><span className="text-primary font-semibold">Network protection</span> — Your sandbox can make outbound requests to the internet (e.g. calling APIs), but no one can connect into your sandbox from the outside.</li>
    <li><span className="text-primary font-semibold">Secure credentials</span> — Your API key and phone number are injected securely at runtime and never appear in logs.</li>
    <li><span className="text-primary font-semibold">Dedicated resources</span> — CPU and memory are reserved for your deployment, so performance is consistent.</li>
  </ul>
</Callout>

### Step-by-step guide

#### Prerequisites

<Prose>- A Guava account</Prose>
<Prose>- A terminal (macOS, Linux, or WSL on Windows)</Prose>

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

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

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

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

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`}
/>

<Callout>
  <span className="text-primary font-semibold">Important:</span> 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.
</Callout>

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

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

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

<Callout>
  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.
</Callout>

### Quick reference

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

<NextLink section="cli-reference" label="CLI Reference" />