### Install NGINX Ingress example

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/addons/custom-helm-charts

Demonstrates adding a specific repository and installing the NGINX Ingress controller.

```bash
# Add the ingress-nginx repository
porter helm -- repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
porter helm -- repo update

# Install the chart
porter helm -- install my-ingress ingress-nginx/ingress-nginx \
  --namespace ingress \
  --create-namespace
```

--------------------------------

### Create application examples

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/standard/cli/command-reference/porter-app

Examples for creating an application interactively, by name, or from a configuration file.

```bash
porter app create
```

```bash
porter app create --name example-app
```

```bash
porter app create --name my-app -f porter.yaml
```

--------------------------------

### Datastore Connection Examples

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/standard/cli/command-reference/porter-datastore-connect

Examples of connecting to a datastore with default and custom local ports.

```bash
porter datastore connect my-postgres
```

```bash
porter datastore connect my-postgres --port 5433
```

--------------------------------

### Push application examples

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/standard/cli/command-reference/porter-app

Examples for pushing an application using the latest commit SHA or a specific tag.

```bash
porter app push my-app
```

```bash
porter app push my-app --tag v1.2.3
```

--------------------------------

### Multi-app and addon configuration example

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/applications/configuration-as-code/addons-porter-yaml

A complete example showing multiple applications and in-cluster datastore addons defined in a single file.

```yaml
apps:
  - version: v2
    name: backend
    services:
      - name: server
        run: ""
        type: web
        instances: 1
        cpuCores: 0.2
        ramMegabytes: 100
        terminationGracePeriodSeconds: 30
        port: 80
        sleep: false
        private: true
    envGroups: # Environment groups can be used to inject environment variables from the addons into the service.
      - cache
      - db
    image:
      repository: nginx
      tag: latest
  - version: v2
    name: frontend
    services:
      - name: dashboard
        run: ""
        type: web
        instances: 1
        cpuCores: 0.2
        ramMegabytes: 100
        terminationGracePeriodSeconds: 30
        port: 80
        sleep: false
        private: true
    envGroups:
      - cache
      - db
    image:
      repository: nginx
      tag: latest
  - version: v2
    name: api
    services:
      - name: worker
        run: ""
        type: worker
        instances: 1
        cpuCores: 0.2
        ramMegabytes: 100
        terminationGracePeriodSeconds: 30
        port: 80
        sleep: false
    envGroups:
      - cache
      - db
    image:
      repository: nginx
      tag: latest
addons:
  - name: cache
    type: redis
    kind: in-cluster
    config:
      storageGigabytes: 2 # Persistent storage size in GB. Cannot be changed after creation.
      cpuCores: 0.1
      ramMegabytes: 110
  - name: db
    type: postgres
    kind: in-cluster
    config:
      storageGigabytes: 2
      cpuCores: 0.1
      ramMegabytes: 110
```

--------------------------------

### Complete Job Service Configuration Example

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/applications/configuration-as-code/services/job-service

A comprehensive example demonstrating job definition, scheduling, resource limits, and cloud connections.

```yaml
services:
  - name: daily-report
    type: job
    run: python generate_report.py
    cpuCores: 1
    ramMegabytes: 2048

    # Schedule: Daily at 6 AM UTC
    cron: "0 6 * * *"

    # Allow up to 2 hours
    timeoutSeconds: 7200

    # Don't allow concurrent runs
    allowConcurrent: false

    # Cloud connections
    connections:
      - type: awsRole
        role: report-s3-access

    # Graceful shutdown
    terminationGracePeriodSeconds: 60
```

--------------------------------

### Porter env create examples

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/standard/cli/command-reference/porter-env

Examples for creating environment groups interactively, non-interactively, and with predefined variables and secrets.

```bash
porter env create
```

```bash
porter env create --name production-secrets
```

```bash
porter env create --name production-secrets \
  -v NODE_ENV=production,LOG_LEVEL=info \
  -s DB_PASSWORD=secret,API_KEY=sk-123
```

--------------------------------

### Install the SDK

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/sdk/python/quickstart

Add the porter-sandbox package to your environment using pip or uv.

```bash
pip install porter-sandbox
```

```bash
uv add porter-sandbox
```

--------------------------------

### Run Azure setup commands

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/cloud-accounts/connecting-a-cloud-account

Executes the setup script provided by Porter to configure workload identity federation in Azure.

```bash
# Authenticate the Azure CLI
az login

# Download the setup script
curl -O https://raw.githubusercontent.com/porter-dev/docs/main/scripts/setup-azure-porter-wif.sh

# Make it executable
chmod +x setup-azure-porter-wif.sh

# Run the script with the OIDC subject and issuer from Porter
./setup-azure-porter-wif.sh \
  --subject <oidc-subject-from-porter> \
  --issuer <oidc-issuer-from-porter>
```

--------------------------------

### Porter App Update-Tag Examples

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/standard/cli/command-reference/porter-app

Examples for updating image tags, including waiting for the rollout to succeed.

```bash
porter app update-tag my-app --tag abc123def
```

```bash
porter app update-tag my-app --tag v1.2.3 --wait
```

--------------------------------

### CI/CD Configuration Example

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/cli/basic-usage

Configures authentication and project/cluster context using environment variables before running a deployment.

```bash
export PORTER_TOKEN="your-deploy-token"
export PORTER_PROJECT="12345"
export PORTER_CLUSTER="67890"

porter apply -f porter.yaml
```

--------------------------------

### Complete application configuration

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/applications/configuration-as-code/reference

A full example demonstrating build settings, environment variables, deployment hooks, and multiple service types.

```yaml
version: v2
name: my-app

build:
  method: docker
  context: .
  dockerfile: ./Dockerfile

env:
  PORT: "8080"
  LOG_LEVEL: "info"

envGroups:
  - production-secrets
  - shared-config

predeploy:
  run: python manage.py migrate
  cpuCores: 0.5
  ramMegabytes: 512

initialDeploy:
  run: python manage.py seed
  cpuCores: 0.25
  ramMegabytes: 256

autoRollback:
  enabled: true

efsStorage:
  enabled: true

services:
  # Web service with all options
  - name: web
    type: web
    run: python app.py
    instances: 2
    cpuCores: 1
    ramMegabytes: 1024
    port: 8080
    terminationGracePeriodSeconds: 30
    autoscaling:
      enabled: true
      minInstances: 2
      maxInstances: 10
      cpuThresholdPercent: 80
      memoryThresholdPercent: 80
    healthCheck:
      enabled: true
      httpPath: /healthz
    domains:
      - name: app.example.com
    metricsScraping:
      enabled: true
      path: /metrics
      port: 9090
      scrapeIntervalSeconds: 30
    connections:
      - type: awsRole
        role: my-app-role

  # GPU-enabled worker on a custom node group
  - name: ml-worker
    type: worker
    run: python ml_worker.py
    instances: 1
    cpuCores: 4
    ramMegabytes: 16384
    gpuCoresNvidia: 1
    nodeGroup: 123e4567-e89b-12d3-a456-426614174000
    terminationGracePeriodSeconds: 60
    serviceMeshEnabled: true

  # Background worker
  - name: worker
    type: worker
    run: python worker.py
    instances: 1
    cpuCores: 0.5
    ramMegabytes: 512

  # Scheduled job
  - name: cleanup
    type: job
    run: python cleanup.py
    cpuCores: 0.5
    ramMegabytes: 256
    cron: "0 0 * * *"
```

--------------------------------

### Porter App Build Examples

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/standard/cli/command-reference/porter-app

Common usage patterns for building applications with different configurations.

```bash
porter app build my-app
```

```bash
porter app build my-app --build-context ./frontend --dockerfile ./frontend/Dockerfile
```

```bash
porter app build my-app --tag v1.2.3
```

```bash
porter app build my-app --build-method pack --builder heroku/builder:22 --attach-buildpacks heroku/nodejs
```

--------------------------------

### Login Methods

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/standard/cli/command-reference/porter-auth

Examples for performing browser-based login or using a specific authentication token.

```bash
porter auth login
```

```bash
porter auth login --token <YOUR_TOKEN>
```

--------------------------------

### Automated Azure setup script

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/getting-started/quickstart

Use this script to create the required role and service principal for Azure integration. Requires Azure CLI installed and authenticated.

```bash
# Download the setup script
curl -O https://raw.githubusercontent.com/porter-dev/docs/main/scripts/setup-azure-porter.sh

# Make it executable
chmod +x setup-azure-porter.sh

# Run the script (optionally provide subscription ID)
./setup-azure-porter.sh [your-subscription-id]
```

--------------------------------

### Disconnect Cloud Account Examples

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/standard/cli/command-reference/porter-cloud-accounts

Examples showing how to disconnect an account by name or by ID with the confirmation prompt skipped.

```bash
porter cloud-accounts disconnect my-aws-account
```

```bash
porter cloud-accounts disconnect 123456789012 --yes
```

--------------------------------

### Porter Sandbox Creation Examples

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/cli

Various configurations for creating sandboxes, including naming, environment variables, volume mounting, and output formatting.

```bash
porter sandbox create alpine:3.20
```

```bash
porter sandbox create alpine:3.20 --name web -- sleep 3600
```

```bash
porter sandbox create ghcr.io/example/tool:latest --env PORT=8080 --tag env=dev --tag owner=me
```

```bash
porter sandbox create ubuntu:24.04 --volume /workspace=my-data -- bash -lc 'ls -la /workspace'
```

```bash
porter sandbox create alpine:3.20 --env-group my-env-group -- sleep 3600
```

```bash
porter sandbox create alpine:3.20 --ttl 2h -- sleep 7200
```

```bash
porter sandbox create ubuntu:24.04 --volume /workspace=my-data --command bash --arg -lc --arg 'ls -la' -o json
```

--------------------------------

### Verify Porter CLI Installation

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/cli/installation

Run this command to confirm the CLI is installed and check the current version.

```bash
porter version
```

--------------------------------

### Complete Web Service Configuration

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/applications/configuration-as-code/services/web-service

A comprehensive example demonstrating service definition, autoscaling, health checks, path routing, and infrastructure settings.

```yaml
services:
  - name: api
    type: web
    run: npm start
    port: 8080
    cpuCores: 1
    ramMegabytes: 1024

    # Autoscaling
    autoscaling:
      enabled: true
      minInstances: 1
      maxInstances: 10
      cpuThresholdPercent: 80
      memoryThresholdPercent: 80

    # Custom domains
    domains:
      - name: example.com

    # Health checks
    livenessCheck:
      enabled: true
      httpPath: /livez
      timeoutSeconds: 1
      initialDelaySeconds: 15
    readinessCheck:
      enabled: true
      httpPath: /readyz
      timeoutSeconds: 1
      initialDelaySeconds: 15

    # Path routing
    pathRouting:
      - path: /api/v1/
        port: 8080
      - path: /api/v2/
        port: 8081
    pathRoutingConfig:
      rewriteMode: rewrite-prefix

    # Ingress configuration
    ingressAnnotations:
      nginx.ingress.kubernetes.io/proxy-connect-timeout: "18000"

    # Service mesh and metrics
    serviceMeshEnabled: true
    metricsScraping:
      enabled: true
      path: /metrics
      port: 9090
      scrapeIntervalSeconds: 60

    # Cloud connections
    connections:
      - type: awsRole
        role: api-s3-access

    # Graceful shutdown
    terminationGracePeriodSeconds: 30
```

--------------------------------

### Porter app run examples

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/standard/cli/command-reference/porter-app

Various ways to execute commands, jobs, and manage resources within an application container.

```bash
porter app run my-app -- bash
```

```bash
porter app run my-app -e -- bash
```

```bash
porter app run my-app --job my-job
```

```bash
porter app run my-app --job my-job --wait
```

```bash
porter app run my-app --job my-job --allow-concurrent
```

```bash
porter app run my-app -- python manage.py migrate
```

```bash
porter app run my-app --cpu 500 --ram 512 -- python heavy_script.py
```

--------------------------------

### Quick Install MCP Clients

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/mcp/overview

Commands to quickly add the Porter MCP server to supported CLI clients.

```bash
# Claude Code
claude mcp add --transport http porter https://mcp.porter.run

# Codex
codex mcp add porter --url https://mcp.porter.run

# OpenCode, prompts for a name, a type, and the URL
opencode mcp add
```

--------------------------------

### List Cloud Accounts Examples

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/standard/cli/command-reference/porter-cloud-accounts

Common patterns for listing cloud accounts, including filtering by provider, status, and output format.

```bash
porter cloud-accounts list
```

```bash
porter cloud-accounts list --provider aws --status connected
```

```bash
porter cloud-accounts list --json
```

--------------------------------

### Comprehensive porter.yaml example

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/applications/configuration-as-code/overview

A detailed v2 configuration file demonstrating various service types, autoscaling, health checks, and environment variables.

```yaml
version: v2
name: my-app

services:
  - name: api
    type: web
    run: node index.js
    port: 8080
    cpuCores: 0.1
    ramMegabytes: 256
    autoscaling:
      enabled: true
      minInstances: 1
      maxInstances: 3
      memoryThresholdPercent: 60
      cpuThresholdPercent: 60
    private: false
    domains:
      - name: test1.example.com
    healthCheck:
      enabled: true
      httpPath: /healthz
  - name: example-wkr
    type: worker
    run: echo 'work'
    port: 8081
    cpuCores: 0.1
    ramMegabytes: 256
    instances: 1
  - name: example-job
    type: job
    run: echo 'hello world'
    allowConcurrent: true
    cpuCores: 0.1
    ramMegabytes: 256
    cron: '*/10 * * * *'

predeploy:
  run: ls

build:
	method: docker
	context: ./
	dockerfile: ./app/Dockerfile

env:
  NODE_ENV: production

envGroups:
- production-env-group
```

--------------------------------

### Porter env pull examples

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/standard/cli/command-reference/porter-env

Examples for pulling environment data, including writing to files, filtering by type, and merging linked groups.

```bash
porter env pull production-secrets
```

```bash
porter env pull production-secrets -f .env.local
```

```bash
porter env pull production-secrets -v
```

```bash
porter env pull production-secrets -s
```

```bash
porter env pull --app my-app --merged
```

--------------------------------

### Configure initialDeploy job

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/applications/configuration-as-code/reference

Defines a one-time setup task to run during the first deployment of a preview environment.

```yaml
initialDeploy:
  run: npm run seed
  cpuCores: 0.25
  ramMegabytes: 256
```

--------------------------------

### Deploy Helm charts via CLI

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/addons/custom-helm-charts

Add repositories and install charts using the Porter Helm wrapper.

```bash
# Add the Helm repository
helm repo add <repo-name> <repo-url>
helm repo update

# Install the chart:
porter helm -- install <release-name> <repo-name>/<chart-name> \
  --namespace <namespace> \
  --values values.yaml
```

--------------------------------

### Complete worker service configuration

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/applications/configuration-as-code/services/worker-service

A comprehensive example demonstrating autoscaling, health checks, cloud connections, and service mesh settings.

```yaml
services:
  - name: queue-processor
    type: worker
    run: npm run worker
    cpuCores: 1
    ramMegabytes: 2048

    # Autoscaling
    autoscaling:
      enabled: true
      minInstances: 2
      maxInstances: 20
      cpuThresholdPercent: 70
      memoryThresholdPercent: 80

    # Health checks
    livenessCheck:
      enabled: true
      command: ./healthcheck.sh
      timeoutSeconds: 5
    readinessCheck:
      enabled: true
      command: ./ready.sh
      timeoutSeconds: 3

    # Cloud connections
    connections:
      - type: awsRole
        role: worker-sqs-access

    # Service mesh
    serviceMeshEnabled: true

    # Graceful shutdown (allow 2 minutes for jobs to complete)
    terminationGracePeriodSeconds: 120
```

--------------------------------

### Define Basic Services in YAML

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/applications/configuration-as-code/reference

Example configuration showing both a standard web service and a web service assigned to a specific node group.

```yaml
services:
  - name: web
    type: web
    run: python app.py
    instances: 1
    cpuCores: 1
    ramMegabytes: 1024
    port: 8080
  - name: web-on-user-node-group
    type: web
    run: python app.py
    instances: 1
    cpuCores: 1
    ramMegabytes: 1024
    port: 8080
    nodeGroup: 123e4567-e89b-12d3-a456-426614174000
```

--------------------------------

### Porter registry push examples

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/standard/cli/command-reference/porter-registry

Various ways to push images, including overriding destinations, building from source, and handling multi-arch builds.

```bash
porter registry push myimage:dev
```

```bash
porter registry push myimage:dev --dest sandboxes/base:v1
```

```bash
porter registry push myimage:dev \
  --build ./app \
  --dockerfile ./app/prod.Dockerfile
```

```bash
DOCKER_BUILDKIT=1 PORTER_BUILDKIT_ARGS="--platform linux/amd64,linux/arm64" \
  porter registry push myimage:dev --build ./app
```

```bash
porter registry push myimage:dev --json | jq -r .image
```

--------------------------------

### Examples for setting environment variables and secrets

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/standard/cli/command-reference/porter-env

Commands to update variables, secrets, or both in an environment group.

```bash
porter env set production-secrets -v LOG_LEVEL=debug,FEATURE_FLAG=true
```

```bash
porter env set production-secrets -s API_KEY=sk-new-key
```

```bash
porter env set production-secrets \
  -v NODE_ENV=production,LOG_LEVEL=info \
  -s DATABASE_URL=postgres://...
```

--------------------------------

### Minimal porter.yaml configuration

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/applications/configuration-as-code/overview

A basic example of a v2 configuration file defining a web service and build settings.

```yaml
version: v2
name: my-app

services:
  - name: web
    type: web
    run: npm start
    port: 3000
    cpuCores: 0.5
    ramMegabytes: 512

build:
  method: docker
  context: .
  dockerfile: ./Dockerfile
```

--------------------------------

### Sandbox execution examples

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/cli

Various methods for executing commands, scripts, and interactive shells within a sandbox.

```bash
porter sandbox exec abc123 -- ls -la /workspace
```

```bash
porter sandbox exec abc123 -- python --version
```

```bash
porter sandbox exec abc123 --command "echo hi && ls /workspace"
```

```bash
porter sandbox exec abc123 -- python -c 'print("ok")'
```

```bash
porter sandbox exec web -it -- sh
```

--------------------------------

### Table output format example

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/cli

Visual representation of the default table output format for sandbox metrics.

```text
┌──────────────┬────────────────────┬────────────────────┐
│    METRIC    │        P50         │        P90         │
├──────────────┼────────────────────┼────────────────────┤
│ cpu cores    │ 0.001 cores (0.1%) │ 0.003 cores (0.3%) │
│ cpu limit    │ 1.000 cores        │                    │
│ memory       │ 1.27 GiB (63.6%)   │ 2.54 GiB (126.9%)  │
│ memory limit │ 2.00 GiB           │                    │
└──────────────┴────────────────────┴────────────────────┘

window: 1h0m0s
```

--------------------------------

### Porter App Update Examples

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/standard/cli/command-reference/porter-app

Common patterns for updating applications, including file-based updates, tag overrides, and waiting for rollout completion.

```bash
porter app update my-app -f porter.yaml
```

```bash
porter app update my-app --tag v1.2.3
```

```bash
porter app update my-app -f porter.yaml --wait
```

--------------------------------

### porter sandbox volume get

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/cli

Retrieves details for a specific sandbox volume by name.

```APIDOC
## porter sandbox volume get

### Description
Shows a single sandbox volume by name, including phase, creation time, and currently attached sandboxes.

### Usage
`porter sandbox volume get <name> [flags]`

### Options
- **name** (string) - Required - The name of the volume to retrieve.
- **-o, --output** (string) - Optional - Output format: `text` or `json`
```

--------------------------------

### Get Sandbox Volume Details

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/cli

Commands to retrieve specific information about a single volume by its name.

```bash
porter sandbox volume get <name> [flags]
```

```bash
porter sandbox volume get my-data
```

```bash
porter sandbox volume get my-data -o json
```

--------------------------------

### Sandbox metrics usage examples

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/cli

Common usage patterns for retrieving sandbox metrics, including time windows and output formatting.

```bash
porter sandbox metrics web
```

```bash
porter sandbox metrics web --since 30m
```

```bash
porter sandbox metrics web -o json
```

```bash
porter sandbox metrics web -o json | jq '.cpu_util_p90_pct'
```

--------------------------------

### Debug container environment paths

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/applications/debug/common-errors

Use these commands after setting the start command to 'sleep infinity' and accessing the shell to verify command availability and environment paths.

```bash
$ which <start-command>
$ echo $PATH
```

--------------------------------

### Terminate Sandbox Examples

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/cli

Common command variations for terminating sandboxes, including dry runs and tag-based filtering.

```bash
porter sandbox terminate abc123
```

```bash
porter sandbox terminate --all --dry-run
```

```bash
porter sandbox terminate --all --tag workflow=agent-run --dry-run
```

```bash
porter sandbox terminate --all --tag workflow=agent-run
```

--------------------------------

### Sandbox Logs Examples

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/cli

Various ways to invoke the logs command, including filtering by time, level, and piping to external tools.

```bash
porter sandbox logs abc123
```

```bash
porter sandbox logs abc123 --since 15m --tail 100
```

```bash
porter sandbox logs abc123 --level error --no-timestamps
```

```bash
porter sandbox logs abc123 --tail 200 | grep -i 'panic\|fatal'
```

--------------------------------

### Get running sandbox names for scripts

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/cli

Outputs a clean list of running sandbox names using jq for parsing.

```bash
porter sandbox list -o json | jq -r '.[] | select(.phase == "running") | .name'
```

--------------------------------

### Create an application

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/standard/cli/command-reference/porter-app

Basic usage syntax for creating and deploying a new application.

```bash
porter app create [flags]
```

--------------------------------

### Install Porter CLI on macOS via Homebrew

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/cli/installation

Use Homebrew to install the Porter CLI on macOS systems.

```bash
brew install porter-dev/porter/porter
```

--------------------------------

### Natural Language Task Examples

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/mcp/overview

Examples of natural language prompts used to interact with the agent for application management and troubleshooting.

```text
Help me deploy my code to Porter.

Why did my latest deploy fail?

My web service keeps restarting, figure out why and fix it.

Help me reduce cost for my apps.

Create a staging copy of my production web service.
```

--------------------------------

### Preview Environment

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/standard/cli/command-reference/porter-apply

Deploys the application to a preview environment.

```bash
# Deploy to a preview environment
porter apply -f porter.yaml --preview
```

--------------------------------

### Prometheus Metrics Output Example

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/applications/observability/custom-metrics-and-autoscaling

Example of the expected Prometheus metrics format for counters, including help and type metadata.

```prometheus
# HELP http_requests_total Total number of HTTP requests
# TYPE http_requests_total counter
http_requests_total{method="post",code="200"} 1027
http_requests_total{method="get",code="200"} 2048
```

--------------------------------

### Valid PromQL Query Examples

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/applications/observability/custom-metrics-and-autoscaling

Examples of PromQL queries that return a single numeric value suitable for custom autoscaling thresholds.

```promql
avg(metric_name)
```

```promql
sum(rate(http_requests_total[5m]))
```

```promql
max(queue_length)
```

--------------------------------

### Create and Manage a Sandbox in Python

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/getting-started

Demonstrates the full lifecycle of a sandbox: creation, command execution, log retrieval, and termination.

```python
from porter_sandbox import Porter

with Porter() as porter:
    sandbox = porter.sandboxes.create(
        image="python:3.12-slim",
        name="getting-started-python",
        tags={"example": "getting-started"},
    )

    result = sandbox.exec(["python", "-c", "print(2 + 2)"])
    print(result.stdout)

    logs = sandbox.logs(limit=100)
    print(logs)

    sandbox.terminate()
```

--------------------------------

### Install Porter CLI via Shell Script

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/cli/installation

Use the shell script to install the Porter CLI on macOS or Linux. Requires curl and unzip utilities.

```bash
/bin/bash -c "$(curl -fsSL https://install.porter.run)"
```

--------------------------------

### Create and execute a sandbox

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/sdk/python/quickstart

Initialize a sandbox, run a command, and terminate the instance.

```python
from porter_sandbox import Porter

with Porter() as porter:
    sandbox = porter.sandboxes.create(
        image="python:3.12-slim",
        name="python-quickstart",
        tags={"example": "python-quickstart"},
    )

    result = sandbox.exec(["python", "-c", "print('hello from porter')"])
    print(result.stdout)

    sandbox.terminate()
```

--------------------------------

### List Helm releases

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/addons/custom-helm-charts

View all installed Helm releases across all namespaces.

```bash
porter helm -- list --all-namespaces
```

--------------------------------

### volume.iterdir(path)

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/sdk/typescript/volumes

Recursively walks the directory tree starting from the specified path.

```APIDOC
## volume.iterdir(path)

### Description
Walks the whole tree, descending into every subdirectory.

### Signature
`volume.iterdir(path: string)`

### Parameters
- **path** (string) - Required - The root directory path to start the walk.
```

--------------------------------

### Viewing Help

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/cli/basic-usage

Displays help instructions for the CLI, specific commands, or subcommands.

```bash
# General help
porter -h

# Help for a specific command
porter app -h

# Help for a subcommand
porter app run -h
```

--------------------------------

### Porter Client Initialization

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/sdk/typescript/reference

How to instantiate the Porter client and configure connection options.

```APIDOC
## Porter Client

### Description
The `Porter` class is the top-level client for interacting with the Sandbox SDK. It provides access to resource namespaces including sandboxes, volumes, health, and readiness.

### Constructor Options
- **apiKey** (string | undefined) - Optional API key. Falls back to `PORTER_SANDBOX_API_KEY`.
- **baseUrl** (string | undefined) - Optional API base URL override. Falls back to `PORTER_SANDBOX_BASE_URL`.
- **timeoutMs** (number | undefined) - Request timeout in milliseconds. Defaults to 30 seconds.

### Example
```typescript
import { Porter } from "porter-sandbox";
const porter = new Porter({ timeoutMs: 5000 });
// ... perform operations
porter.close();
```
```

--------------------------------

### Get a Sandbox by Name

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/sdk/typescript/reference

Retrieves a sandbox handle using its canonical name.

```typescript
const sandbox = await porter.sandboxes.get("my-sandbox");
```

--------------------------------

### Creating a Sandbox with Porter

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/sdk/python/reference

Initialize the Porter client and create a new sandbox using the context manager pattern.

```python
from porter_sandbox import Porter

with Porter() as porter:
    sandbox = porter.sandboxes.create(
        image="python:3.12-slim",
        name="my-sandbox",
    )
```

--------------------------------

### Get a volume by name

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/sdk/typescript/volumes

Retrieves a volume object by its unique name within the cluster.

```typescript
import { Porter } from "porter-sandbox";

const porter = new Porter();
const volume = await porter.volumes.get("agent-workspace");

console.log(volume.id);

porter.close();
```

--------------------------------

### create

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/sdk/typescript/reference

The create method initializes a new sandbox environment with the specified configuration and returns a Sandbox handle.

```APIDOC
## create

### Description
Creates and starts a new sandbox instance with the provided configuration options.

### Parameters
- **image** (string) - Required - Container image to run, referenced by tag or digest.
- **name** (string | undefined) - Optional - Optional cluster-unique sandbox name.
- **command** (string[] | undefined) - Optional - Optional entrypoint override.
- **args** (string[] | undefined) - Optional - Optional arguments passed to the command.
- **env** (Record<string, string> | undefined) - Optional - Environment variables to set in the sandbox.
- **env_groups** (string[] | undefined) - Optional - Names of environment groups to inject into the sandbox.
- **tags** (Record<string, string> | undefined) - Optional - Key-value labels for finding related sandboxes.
- **volume_mounts** (Record<string, string> | undefined) - Optional - Volume IDs keyed by absolute mount path inside the sandbox.
- **networking** (SandboxNetworkingSpec[] | undefined) - Optional - Port to expose and, optionally, the domain and visibility.
- **egress** (SandboxEgressSpec | undefined) - Optional - Restricts the sandbox's outbound traffic.
- **ttl_seconds** (number | undefined) - Optional - Maximum lifetime in seconds, counted from creation.

### Returns
- **Sandbox** (handle) - A handle to the created sandbox.
```

--------------------------------

### Get a sandbox by name

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/sdk/python/quickstart

Retrieve an existing sandbox instance using its unique name.

```python
from porter_sandbox import Porter

with Porter() as porter:
    sandbox = porter.sandboxes.get("python-quickstart")
    print(sandbox.phase)
```

--------------------------------

### Create a sandbox with the Python SDK

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/sdk/python/reference

Initializes a new sandbox instance with a specified container image and optional configuration parameters.

```python
sandbox = porter.sandboxes.create(
    image="python:3.12-slim",
    name="my-sandbox",
    command=None,
    args=None,
    env=None,
    tags={"workflow": "demo"},
    volume_mounts=None,
)
```

--------------------------------

### Define chart configuration

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/addons/custom-helm-charts

Example structure for storing chart metadata and values in version control.

```yaml
# chart.yaml
chartUrl: https://custom-chart-repo.com
version: 1.0.0
```

```yaml
# values.yaml
replicaCount: 3
resources:
  limits:
    cpu: 100m
    memory: 128Mi
```

--------------------------------

### With Environment Variables

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/standard/cli/command-reference/porter-apply

Deploys the application while injecting runtime environment variables and secrets.

```bash
# Deploy with runtime environment variables and secrets
porter apply -f porter.yaml --variables LOG_LEVEL=debug,NODE_ENV=production --secrets API_KEY=secret123
```

--------------------------------

### Get a volume by name

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/sdk/python/volumes

Retrieve a volume instance using its unique name within the cluster.

```python
with Porter() as porter:
    volume = porter.volumes.get("agent-workspace")
    print(volume.id)
```

--------------------------------

### CI/CD Deployment Workflow

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/cli/basic-usage

Deploys an application by passing configuration directly via environment variables.

```bash
# Deploy with explicit configuration
PORTER_TOKEN=$DEPLOY_TOKEN \
PORTER_PROJECT=$PROJECT_ID \
PORTER_CLUSTER=$CLUSTER_ID \
porter apply -f porter.yaml
```

--------------------------------

### Create and manage a sandbox

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/sdk/typescript/quickstart

Initialize a client, create a sandbox, execute a command, and ensure cleanup with a finally block.

```typescript
import { Porter } from "porter-sandbox";

const porter = new Porter();

const sandbox = await porter.sandboxes.create({
  image: "python:3.12-slim",
  name: "typescript-quickstart",
  tags: { example: "typescript-quickstart" },
});

try {
  const result = await sandbox.exec(["python", "-c", "print('hello from porter')"]);
  console.log(result.stdout);
} finally {
  await sandbox.terminate();
  porter.close();
}
```

--------------------------------

### Examples for removing environment variables and secrets

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/standard/cli/command-reference/porter-env

Commands to remove specific variables or secrets from an environment group.

```bash
porter env unset production-secrets -v OLD_KEY,UNUSED_VAR
```

```bash
porter env unset production-secrets -s ROTATED_KEY,OLD_SECRET
```

```bash
porter env unset production-secrets -v VAR1 -s SECRET1
```

--------------------------------

### Invalid PromQL Query Examples

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/applications/observability/custom-metrics-and-autoscaling

Categories of queries that are not supported for autoscaling because they do not return a single scalar value.

```text
Vector results (multiple time series)
```

```text
String results
```

```text
No data/empty results
```

--------------------------------

### Create and Execute in Sandbox

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/getting-started

Initialize a sandbox, run a Python command, retrieve logs, and terminate the instance.

```typescript
import { Porter } from "porter-sandbox";

const porter = new Porter();

const sandbox = await porter.sandboxes.create({
  image: "python:3.12-slim",
  name: "getting-started-typescript",
  tags: { example: "getting-started" },
});

const result = await sandbox.exec(["python", "-c", "print(2 + 2)"]);
console.log(result.stdout);

const logs = await sandbox.logs({ limit: 100 });
console.log(logs);

await sandbox.terminate();
porter.close();
```

--------------------------------

### Basic porter apply usage

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/standard/cli/command-reference/porter-apply

Execute a deployment using a specific configuration file and optional flags.

```bash
porter apply -f porter.yaml [flags]
```

--------------------------------

### Create and mount a volume

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/volumes

Create a volume and attach it to a sandbox by specifying the mount path and volume ID.

```python
from porter_sandbox import Porter

with Porter() as porter:
    volume = porter.volumes.create(name="agent-workspace")
    sandbox = porter.sandboxes.create(
        image="python:3.12-slim",
        volume_mounts={"/workspace": volume.id},
    )
```

```typescript
import { Porter } from "porter-sandbox";

const porter = new Porter();
const volume = await porter.volumes.create({ name: "agent-workspace" });
const sandbox = await porter.sandboxes.create({
  image: "python:3.12-slim",
  volume_mounts: { "/workspace": volume.id },
});
```

```bash
porter sandbox volume create agent-workspace
porter sandbox create python:3.12-slim --volume /workspace=agent-workspace -- sleep infinity
```

--------------------------------

### Initialize Porter and create a sandbox

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/sdk/typescript/reference

Instantiate the Porter client and use it to create a new sandbox with a specified image and name.

```typescript
const porter = new Porter();
const sandbox = await porter.sandboxes.create({
  image: "python:3.12-slim",
  name: "my-sandbox",
});
```

--------------------------------

### JSON output structure for environment groups

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/standard/cli/command-reference/porter-env

Example of the JSON schema returned when using the --json flag.

```json
{
  "environment_groups": [
    {
      "id": "2a54d3ab-08e2-4922-9368-a7e45ad87d23",
      "name": "tessier-internal",
      "current_version": 9,
      "created_at": "2026-02-25T09:23:16.332254Z",
      "updated_at": "2026-06-30T04:23:25.23501Z",
      "sync_target_cluster_ids": [11]
    }
  ],
  "cluster_scoped_environment_groups": [
    {
      "id": "",
      "name": "billing-db",
      "current_version": 202,
      "created_at": "2025-10-27T16:00:48Z",
      "updated_at": "2025-10-27T16:00:48Z",
      "sync_target_cluster_ids": [11]
    }
  ]
}
```

--------------------------------

### Basic Deployment

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/standard/cli/command-reference/porter-apply

Deploys an application using the porter.yaml file located in the current directory.

```bash
# Deploy using porter.yaml in the current directory
porter apply -f porter.yaml
```

--------------------------------

### List Projects

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/cli/basic-usage

Lists all available projects accessible to the authenticated user.

```bash
porter projects list
```

--------------------------------

### Porter Job Runs Examples

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/standard/cli/command-reference/porter-job

Various ways to filter and limit job run results using flags.

```bash
porter job runs
```

```bash
porter job runs --job my-job
```

```bash
porter job runs --app my-app
```

```bash
porter job runs --app my-app --revision 3
```

```bash
porter job runs --target ALL
```

```bash
porter job runs --status successful
```

```bash
porter job runs --limit 25
```

--------------------------------

### Configure Startup Check

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/applications/configuration-as-code/services/worker-service

Defines the startup probe for containers with slow initialization; other probes remain disabled until this passes.

```yaml
startupCheck:
  enabled: true
  command: ./startupz.sh
  timeoutSeconds: 10
  initialDelaySeconds: 0
```

--------------------------------

### Deploying configuration with Porter CLI

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/applications/configuration-as-code/addons-porter-yaml

Use the apply command to deploy the configuration defined in your porter.yaml file.

```bash
porter apply -f porter.yaml --wait
```

--------------------------------

### Start Temporal Workflow via API

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/applications/configure/temporal-autoscaling

Initiates a document processing workflow upon receiving a file upload request.

```python
from temporalio.client import Client

@app.post("/upload")
async def upload_document(file: UploadFile):
    # Start a Temporal workflow for each uploaded document
    await temporal_client.start_workflow(
        ProcessDocumentWorkflow.run,
        args=[file.filename],
        id=f"doc-{uuid4()}",
        task_queue="document-processing"
    )
    return {"status": "processing"}
```

--------------------------------

### Create a sandbox with an environment group

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/cli

Initializes a sandbox associated with a specific environment group.

```bash
porter sandbox create alpine:3.20 --env-group my-env-group -- sleep 3600
```

--------------------------------

### Create and Manage an In-Sandbox Agent

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/getting-started

Deploy an agent using a custom image and environment variables, then monitor its output and manage its lifecycle.

```python
sandbox = porter.sandboxes.create(
    image="ghcr.io/acme/agent:latest",
    name="research-agent",
    env={"MODEL_API_KEY": model_api_key},
)

# Follow the agent's output while it runs.
print(sandbox.logs(limit=100))

# Terminate when you're done, or let the agent's process exit on its own.
sandbox.terminate()
```

```typescript
const sandbox = await porter.sandboxes.create({
  image: "ghcr.io/acme/agent:latest",
  name: "research-agent",
  env: { MODEL_API_KEY: modelApiKey },
});

// Follow the agent's output while it runs.
console.log(await sandbox.logs({ limit: 100 }));

// Terminate when you're done, or let the agent's process exit on its own.
await sandbox.terminate();
```

```bash
porter sandbox create ghcr.io/acme/agent:latest --name research-agent --env MODEL_API_KEY=$MODEL_API_KEY
```

--------------------------------

### Deploy using version-controlled values

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/addons/custom-helm-charts

Extract configuration from files and deploy using the Porter CLI.

```bash
CHART_URL=$(yq e '.chartUrl' porter-custom-helm-chart-addons/custom-chart/chart.yaml)
VERSION=$(yq e '.version' porter-custom-helm-chart-addons/custom-chart/chart.yaml)

porter helm -- install custom-chart $CHART_URL \
  --version $VERSION \
  --values porter-custom-helm-chart-addons/custom-chart/values.yaml
```

--------------------------------

### Create Sandbox Command Syntax

Source: https://porter-adi-run-4007-chore-make-the-agent-path-more-prominen.mintlify.site/sandboxes/cli

The base command structure for creating a sandbox from a container image.

```bash
porter sandbox create <image> [-- <command> [args...]] [flags]
```