Deploying a Private Location¶

To deploy a Private Location, review the prerequisites and retrieve your API key. Creating, editing, and deleting locations requires the global Admin permission.

To get your API key, go to your profile page. Now save it in your environment variables as ESCAPE_API_KEY=....

Using the Escape CLI¶

If you've installed the Escape CLI, you can manage your Private Locations with the following commands:

escape-cli locations start location-name

This starts a new Private Location on your computer and automatically connects it to your Escape account. If the location doesn't exist, it's created automatically. You can see its status on the Private Locations page.

Using Helm¶

helm repo add escape-cli https://escape-technologies.github.io/cli/
helm repo update

# Get your API key from https://app.escape.tech/user/profile/
helm install escape-private-location escape-cli/private-location --set ESCAPE_API_KEY="${ESCAPE_API_KEY}"

The Helm chart sets HEALTH_CHECK_PORT=8080, ESCAPE_CLI_RESTART_INTERVAL=24h, and a Kubernetes liveness probe on GET /health. The health check is configured by default. See Environment Variables for the full configuration reference.

The chart enables Kubernetes integration and creates cluster-wide read permissions by default. See Kubernetes Integration and RBAC. To disable it, add --set ESCAPE_K8S_INTEGRATION=false.

For controlled upgrades, pin container.image to a released version tag. With the default escapetech/cli:latest and imagePullPolicy: Always, Helm deployments can pull a newer image when a container restarts, including after the scheduled restart. Docker Compose restarts don't automatically pull a newer image.

Using Docker¶

You can start a Private Location with Docker by running:

docker run \
  -e ESCAPE_API_KEY="${ESCAPE_API_KEY}" \
  -e HEALTH_CHECK_PORT=8080 \
  -p 8080:8080 \
  -it --rm escapetech/cli:latest locations start location-name

Set HEALTH_CHECK_PORT so the container serves GET /health. Orchestrators such as Kubernetes use that endpoint to decide whether the application is healthy and whether the deployment can complete. See Health Check for the response codes and probe timing.

The image entrypoint is escape-cli, so you pass only its arguments (locations start location-name), never the binary name. Every orchestrator that appends arguments to the entrypoint (Docker, Compose, Kubernetes args, Convox command:) follows the same rule.

Using Podman¶

If you prefer Podman, you can use:

podman run \
  -e ESCAPE_API_KEY="${ESCAPE_API_KEY}" \
  -e HEALTH_CHECK_PORT=8080 \
  -p 8080:8080 \
  -it --rm escapetech/cli:latest locations start location-name

Using Docker Compose¶

---
services:
  private-location:
    image: escapetech/cli:latest
    restart: always
    command: locations start -v location-name
    ports:
      - "8080:8080"
    environment:
      - ESCAPE_API_KEY=<ESCAPE_API_KEY>
      - HEALTH_CHECK_PORT=8080

/health is served on the mapped port and returns 503 until the location is connected.

Compose's restart: always only reacts to the container process exiting, never to an unhealthy status.

Poll /health and restart the container when it stops returning 200. Use the address that's reachable from wherever the poller runs:

localhost only works from the Docker host itself. From another container it resolves to that container, not to the Private Location.

If you want the restart handled for you, deploy on Kubernetes with the liveness probe below, or use the Helm chart.

Using Convox¶

Convox maps command: to the container arguments appended to the image entrypoint. Use the official image directly with the configuration below.

services:
  private-location:
    image: escapetech/cli:latest
    command: locations start location-name
    port: 8080
    health:
      path: /health
      grace: 60
      interval: 30
      timeout: 5
    environment:
      - ESCAPE_API_KEY
      - HEALTH_CHECK_PORT=8080

Don't put escape-cli in command:. The image entrypoint is already escape-cli, so command: locations start location-name runs escape-cli locations start location-name. Adding the binary name would run escape-cli escape-cli locations start location-name and fail.

health reuses the service port, so keep HEALTH_CHECK_PORT equal to it. Give the check a grace period: /health returns 503 until the tunnel is connected, and a grace that's too short makes Convox recycle the container before it ever connects.

Keep the health port accessible only to your health checker, rather than exposing it publicly. The health server also serves unauthenticated POST /log when you enable that endpoint.

Set ESCAPE_API_KEY as a Convox environment variable (convox env set ESCAPE_API_KEY=...) rather than committing it to convox.yml.

Health Check¶

The Private Location starts an HTTP server only when HEALTH_CHECK_PORT is set. If the variable is empty, there's no /health endpoint.

The examples use port 8080 for the health server.

Once the server is up, query http://<host>:<HEALTH_CHECK_PORT>/health:

For a Kubernetes Deployment that doesn't use the Helm chart, set the same environment variable and probe as the chart:

env:
  - name: HEALTH_CHECK_PORT
    value: "8080"
livenessProbe:
  httpGet:
    path: /health
    port: 8080
  initialDelaySeconds: 60
  periodSeconds: 60
  failureThreshold: 60

Use /health to detect a disconnected location and have your orchestrator restart it. See Environment Variables for the restart and health settings.