Deploying a Private Location¶

To deploy a Private Location, you only need to retrieve your API key from the platform. With the API key, you will be able to create locations, list them, and delete them.

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 have installed the Escape CLI, you can manage your Private Locations with the following commands:

escape-cli locations start location-name

This will start a new Private Location on your computer and will automatically connect it to your Escape account. If the location does not exist, it will be created, and you will be able to see its status in the Escape platform 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. You don't need extra configuration for the health check when you deploy with Helm. See Environment Variables for the full configuration reference.

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 can't restart the container on its own when the location is unhealthy:

• The image is distroless, with no shell or curl, so a Compose healthcheck has nothing to run inside the container.
• 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, so the official image works as is. You don't need to build or maintain a custom image.

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.

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.

Use a port of 1024 or higher. The image runs as a non-root user (uid 65532), which can't bind privileged ports.

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.