> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ppio.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Build a template with the CLI

> Build a Dockerfile into a reusable sandbox template with ppio template create, setting the start and ready commands, CPU count, memory and build cache.

The CLI builds a Dockerfile directly into a reusable sandbox template. It reads the Dockerfile, builds the image, applies the sandbox settings for the start command, ready command, CPU and memory, and registers the result under the template name. Sandboxes are then created from that name with `sandbox.create(...)`.

> [!NOTE]
>
> Authentication is required. Sign in with `ppio auth login`, or set `PPIO_API_KEY` in the environment.

## Build a template

**1. Write the Dockerfile**

Create `ppio.Dockerfile` in the root directory. Without `--dockerfile`, the CLI looks for `ppio.Dockerfile` first and falls back to `Dockerfile`.

```dockerfile ppio.Dockerfile theme={null}
FROM python:3.12

WORKDIR /home/user/app

RUN pip install --no-cache-dir flask requests

COPY app.py .

ENV PORT=8080

CMD ["python", "app.py"]
```

**2. Run the build**

Pass the template name. The name must be lowercase and contain only letters, numbers, dashes and underscores.

```bash CLI theme={null}
ppio template create my-python-template
```

**3. Create a sandbox from the template**

Once the build finishes, create sandboxes from the template by name.

```bash CLI theme={null}
ppio sandbox create my-python-template -d
```

## Files read by the build

The minimal build reads these two files from the current directory.

**my-python-template**

**app.py**

**ppio.Dockerfile**

## Usage

```bash CLI theme={null}
ppio template create <template-name> [options]
```

**\<template-name>** `string` *required*

Template name to create or rebuild. The name must be lowercase and contain only letters, numbers, dashes and underscores, matching `^[a-z0-9-_]+$`.

## Options

**-p, --path** `string`

Root directory where the command runs. Defaults to the current directory. Dockerfile lookup and the build file context resolve relative to it.

**-d, --dockerfile** `string`

Path to the Dockerfile, relative to the root directory. Without this option, the CLI looks for `ppio.Dockerfile` first and falls back to `Dockerfile`.

**-c, --cmd** `string`

Command that runs when the sandbox starts. Must be used together with `--ready-cmd`.

**--ready-cmd** `string`

Command that must exit with code 0 for the template to be considered ready. Can be used on its own.

**--cpu-count** `number` (default: 2)

Number of CPUs used to run the sandbox.

**--memory-mb** `number` (default: 1024)

Memory in megabytes used to run the sandbox. Must be an even number.

**--no-cache** `boolean`

Skips the build cache when building the template.

**--patch-cmd** `string`

Command that patches an incompatible base image at the end of the provision phase.

## Behavior and validation

* `--cmd` and `--ready-cmd` must be provided together. A build that passes `--cmd` without `--ready-cmd` fails. `--ready-cmd` alone is allowed.
* An invalid template name, or an odd value for `--memory-mb`, aborts the build before anything is sent to the server.
* Build logs stream to the terminal. On success, the CLI prints Python and Node.js snippets that show how to create a sandbox from the new template.

## Examples

Reads `./ppio.Dockerfile`, or `./Dockerfile`, in the current directory:

```bash CLI theme={null}
ppio template create my-python-template
```

Points the build at a specific Dockerfile relative to the root directory:

```bash CLI theme={null}
ppio template create my-python-template --dockerfile ./Dockerfile
```

A custom root directory, resources, start and ready commands, and no cache:

```bash CLI theme={null}
ppio template create my-python-template \
  --path ./app \
  --dockerfile ./docker/ppio.Dockerfile \
  --cpu-count 4 \
  --memory-mb 2048 \
  --cmd "python app.py" \
  --ready-cmd "curl -sf http://localhost:8080/health" \
  --no-cache
```

## Create a sandbox from the template

Create sandboxes from the template by name with the SDK:

```javascript Node.js theme={null}
// index.mts
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create('my-python-template')

await sandbox.kill()
```


## Related topics

- [Build a template with the SDK](https://docs.ppio.ai/sandbox/templates/build.md)
- [Mount an S3 bucket in a sandbox](https://docs.ppio.ai/sandbox/filesystem/mount-s3.md)
- [What is a sandbox template?](https://docs.ppio.ai/sandbox/templates/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.