# Locations Management

Locations define where Escape executes security scans. They enable you to test applications in different network environments, including those behind firewalls or in private networks.

## Understanding Locations

Locations use two types:

- **Escape Locations** - Escape's managed cloud infrastructure for testing publicly accessible applications
- **Private Locations** - Self-hosted agents deployed in your infrastructure for testing private applications

For comprehensive information about Private Locations, see the [Private Locations documentation](<https://docs.escape.tech/documentation/platform/private-location/index.md>).

## Location Types Comparison

| Feature | Escape Locations | Private Locations |
| --- | --- | --- |
| **Deployment** | Managed by Escape | Self-hosted |
| **Target Applications** | Public internet | Private networks |
| **Setup Complexity** | None | Kubernetes deployment |
| **Firewall Access** | Not required | Required for private apps |
| **Use Case** | Public APIs, web apps | Internal services, VPNs |

## Listing Locations

View all configured locations in your organization.

```bash
escape-cli locations list
```

**Aliases:** `list`, `ls`

**Table Columns:** `ID`, `NAME`, `TYPE`, `ENABLED`, `LAST SEEN`, `LINK`.

### Filtering Locations

Narrow your location list using filters:

```bash
# Show only enabled locations
escape-cli locations list --enabled

# Filter by location type
escape-cli locations list --type private

# Search by name
escape-cli locations list --search "production"

# Combine filters
escape-cli locations list --type private --enabled
```

**Available filters:**

| Flag | Description | Values |
| --- | --- | --- |
| `-e, --enabled` | Only enabled locations | \- |
| `-s, --search` | Search by name | Any string |
| `-t, --type` | Filter by type | `escape`, `private` (case-insensitive) |

**API Reference:** [GET /locations](<https://public.escape.tech/v3/#tag/locations/get/locations>)

## Getting Location Details

Retrieve detailed information about a specific location.

```bash
escape-cli locations get <location-id>
```

**Example:**

```bash
escape-cli locations get 11111111-1111-1111-1111-111111111111
```

Pretty output shows the location ID, name, type, enabled status, and link. JSON output also includes `createdAt` and `lastSeenAt` when available:

```bash
escape-cli locations get <location-id> -o json | jq '{id, name, enabled, lastSeenAt}'
```

**Alias:** `g`

## Starting a Private Location

Run a Private Location agent using the CLI. The command generates SSH keys and registers the location automatically, creating it if it doesn't exist.

```bash
escape-cli locations start <location-name>
```

**Example:**

```bash
escape-cli locations start corporate-vpn
```

> [!NOTE]
>
> **Long-Running Process**
>
> The `locations start` command runs continuously until interrupted with `Ctrl+C`. The location agent maintains an active connection to the Escape platform and processes scan requests.

### Running as a Service

For production deployments, run Private Locations as a systemd service or Kubernetes deployment:

**Systemd Service Example:**

```ini
[Unit]
Description=Escape Private Location
After=network.target

[Service]
Type=simple
User=escape
Environment=ESCAPE_API_KEY=your-api-key
ExecStart=/usr/local/bin/escape-cli locations start corporate-vpn
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

**Kubernetes Deployment:**

See the [Private Locations deployment guide](<https://docs.escape.tech/documentation/platform/private-location/deployment/index.md>) for complete Kubernetes configuration examples.

## Creating and Updating Locations

For manual registration, use a name and your agent's SSH public key:

```bash
escape-cli locations create --name corporate-vpn --ssh-public-key "$(cat agent-key.pub)"
escape-cli locations update <location-id> --name corporate-vpn --enabled true
```

`locations update` accepts `--name`, `--ssh-public-key`, and `--enabled`. Supply at least one. Use `locations start` for automatic registration and agent startup.

## Deleting a Location

Remove a location from your organization.

```bash
escape-cli locations delete <location-id>
```

**Aliases:** `delete`, `del`, `remove`

**Example:**

```bash
escape-cli locations delete 22222222-2222-2222-2222-222222222222
```

> [!WARNING]
>
> **Deletion Considerations**
>
> - Profiles using this location will need to be reconfigured
> - Running scans using this location will fail
> - This action can't be undone

**API Reference:** [DELETE /locations/{id}](<https://public.escape.tech/v3/#tag/locations/delete/locations/%7BlocationId%7D>)

## Choosing the Right Location

### Use Escape Locations When:

- Testing publicly accessible applications
- You don't have specific network requirements
- Quick setup is a priority
- You're testing APIs or web apps on the public internet

### Use Private Locations When:

- Testing applications behind firewalls
- Applications are in private networks (VPNs, intranets)
- Compliance requires on-premises testing
- You need custom network configurations
- Testing requires access to internal services

## Private Location Setup

### 1\. Deploy the Location Agent

`locations start` registers the location by name as part of agent startup.

Deploy using the CLI command:

```bash
escape-cli locations start <location-name>
```

Or deploy in Kubernetes for production:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: escape-private-location
spec:
  replicas: 1
  selector:
    matchLabels:
      app: escape-private-location
  template:
    metadata:
      labels:
        app: escape-private-location
    spec:
      containers:
      - name: escape-cli
        image: escapetech/cli:latest
        command: ["escape-cli", "locations", "start", "location-name"]
        env:
        - name: ESCAPE_API_KEY
          valueFrom:
            secretKeyRef:
              name: escape-api-key
              key: api-key
```

### 2\. Verify Location Health

Check that the location is connected and healthy:

```bash
escape-cli locations list --search "<location-name>"
```

Look for:

- `ENABLED: true`
- A recent `LAST SEEN` timestamp

### 3\. Configure Profiles to Use the Location

Update your profiles to use the Private Location:

```bash
# Get the location ID
LOCATION_ID=$(escape-cli locations list --search "location-name" -o json | jq -r '.[0].id')

# Use it when creating profiles
cat <<EOF > profile.json
{
  "assetId": "<asset-id>",
  "name": "Internal API Profile",
  "proxyId": "$LOCATION_ID",
  "extraAssetIds": ["<schema-id>"],
  "tagsIds": []
}
EOF

escape-cli profiles create-rest < profile.json
```

## Monitoring Location Health

### Check Location Status

```bash
# List locations with their last-seen timestamps
escape-cli locations list

# Get specific location details
escape-cli locations get <location-id> -o json | jq '{enabled, lastSeenAt}'
```

### Health Indicators

Check `enabled` and `lastSeenAt`. `LAST SEEN` in `locations list` is the heartbeat indicator; there's no `health` field or `HEALTHY`/`CONNECTED` status in the response.

### Troubleshooting Unhealthy Locations

If a location appears unhealthy:

```bash
# Check location status
escape-cli locations get <location-id>

# Verify the agent is running (if self-hosted)
ps aux | grep "escape-cli locations start"

# Check agent logs
journalctl -u escape-private-location -f  # If using systemd

# Restart the location agent
escape-cli locations start <location-name>
```

## Network Configuration

### Outbound Connectivity

Private Locations need outbound connectivity to:

- `public.escape.tech`: HTTPS on port 443 for API requests
- `private-location.escape.tech`: TCP on port 2222 for the SSH tunnel

### Firewall Rules

Allow both destinations and ports above.

See [Private Location Firewall Configuration](<https://docs.escape.tech/documentation/platform/firewall/index.md>) for detailed rules.

### Proxy Support

`ESCAPE_FRONTEND_PROXY_URL` configures the proxy to Escape; `ESCAPE_BACKEND_PROXY_URL` configures the Private Location proxy to scan targets. Standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` variables aren't used for Escape API requests. For example:

```bash
export ESCAPE_FRONTEND_PROXY_URL=http://proxy.example.com:8080
export ESCAPE_BACKEND_PROXY_URL=http://proxy.example.com:8080

escape-cli locations start <location-name>
```

See [Private Location Proxy Configuration](<https://docs.escape.tech/documentation/platform/private-location/proxy/index.md>) for advanced proxy setups.

## Best Practices

### Location Naming

Use descriptive names that indicate:

- **Environment**: production, staging, development
- **Network**: corporate-vpn, aws-vpc, azure-vnet
- **Region**: us-east, eu-west, asia-pacific

**Examples:**

```text
production-us-east-vpc
staging-corporate-network
development-local
```

### High Availability

For critical environments, deploy multiple location agents:

- Run multiple replicas in Kubernetes
- Deploy across availability zones
- Monitor location health continuously

### Security

- Rotate API keys regularly
- Use dedicated service accounts for locations
- Restrict network access to required destinations only
- Monitor location access logs

### Resource Allocation

Private Location agents require:

- **CPU**: 1-2 cores minimum
- **Memory**: 2-4GB RAM minimum
- **Network**: Stable outbound connectivity
- **Storage**: Minimal (logs only)

Scale resources based on scan volume and concurrency.

## Migration from Repeater

If you're using legacy Repeater locations:

1. Deploy new Private Locations
2. Update profiles to use Private Locations
3. Test thoroughly in non-production environments
4. Migrate production profiles
5. Decommission Repeater locations

See [Repeater to Private Location Migration](<https://docs.escape.tech/documentation/platform/private-location/repeater-migration/index.md>) for detailed migration steps.

## Troubleshooting

### Location Not Appearing in List

If a location doesn't appear:

- Start the agent with `escape-cli locations start <location-name>` to register it
- Check your API key has the correct organization access
- Refresh the list: `escape-cli locations list`

### Can't Start Private Location

If registration fails, check API authentication and connectivity. `locations start` creates a missing location automatically.

**Error: "Authentication failed"**

- Verify `ESCAPE_API_KEY` is set correctly
- Check the API key has location management permissions

### Scans Failing with Location Errors

If scans fail due to location issues:

- Verify location is healthy: `escape-cli locations get <location-id>`
- Check location agent logs for errors
- Ensure network connectivity to target applications
- Verify firewall rules allow required traffic

## Next Steps

- **[Private Locations Documentation](<https://docs.escape.tech/documentation/platform/private-location/index.md>)** - Comprehensive Private Location setup guide
- **[Profiles Management](<https://docs.escape.tech/documentation/automate/cli/profiles/index.md>)** - Configure profiles to use locations
- **[Scans Management](<https://docs.escape.tech/documentation/automate/cli/scans/index.md>)** - Run scans using configured locations
- **[Practical Recipes](<https://docs.escape.tech/documentation/automate/cli/recipes/index.md>)** - Complete location setup examples