# Connecting to Your Service via SSH


:::important
SSH access is available only for runtime services and web servers.

Database services, message brokers, and object storage are **not accessible** via SSH.
:::

:::warning Non-Persistent Changes
SSH connections should not be used for making persistent changes to your service:

- In [HA mode](/features/scaling#horizontal-scaling-runtime-services-linux-containers-and-docker), changes via SSH affect only the current container
- Container replacements or scaling events will deploy the original application version
- For persistent changes across all containers, use:
  - [`run.prepareCommands`](/zerops-yaml/specification#preparecommands--1)
  - [`run.initCommands`](/zerops-yaml/specification#initcommands-)
:::

## Connection Methods

You can connect to your services using two methods:

### Web Terminal (Always Available)
For quick debugging and inspection, use the **Remote Web Terminal** available in each service's detail page. This browser-based terminal:
- **Always accessible** regardless of [SSH isolation](#ssh-access-control) settings
- Requires no VPN setup
- Provides instant access to your containers
- Perfect for quick debugging sessions and emergency access

### SSH via VPN (Full Access)
For full SSH capabilities and persistent connections, connect through the [Zerops VPN](/references/networking/vpn).

## Setting Up SSH Access

### 1. Configure VPN Connection (For SSH Access)

The [Zerops CLI (zCLI)](/references/cli) comes bundled with the [Zerops VPN](/references/networking/vpn) client. To connect to your [Zerops project](/features/infrastructure#projects):

1. [Install and configure zCLI](/references/cli)
2. [Initialize the Zerops VPN connection](/references/networking/vpn#start-vpn)

### 2. Establish SSH Connection via VPN

Once your VPN session is active, you can connect to any [service](/features/infrastructure#services) using its hostname via SSH:

```sh
ssh <service hostname>
```

Example:
```sh
ssh app
```

When connecting for the first time, you may receive this security prompt:

```sh title="bash"
The authenticity of host 'app (x.x.x.x)' can't be established.
RSA key fingerprint is SHA256:5wdgRcp/...
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])?
```

Type `yes` to trust the host and prevent future prompts.

#### Connecting to Specific Containers

To access a specific container instead of the service as a whole, use the container's hostname:

```sh
ssh <container hostname>
```

Example:
```sh
ssh node-id-1.runtime.app.zerops
```

:::note
When using [HA mode](/features/scaling#horizontal-scaling-runtime-services-linux-containers-and-docker), connecting to the service hostname will route you to a random container within that service.
:::

#### Container Naming Conventions

Each container in your project has a unique hostname following these patterns:

- Format 1: `node-id-<number>.runtime.app.zerops`
- Format 2: `node<number>.runtime.app.zerops`

When your application [scales horizontally](/features/scaling#horizontal-scaling-runtime-services-linux-containers-and-docker):
- New containers receive incremental hostnames
- Decommissioned container hostnames are not recycled
- You might see non-sequential container numbers (e.g., `node-id-5` and `node-id-12`)
- Container hostnames may change as your service scales

:::warning
Never connect to containers using their local IP addresses, as these addresses are dynamic and may change.
:::

## SSH Access Control

Zerops provides fine-grained control over SSH access through SSH Isolation. It is configured with the `sshIsolation` project variable. This security feature determines who can connect to your services via SSH, controlling both VPN connections and service-to-service SSH access.

### Default Behavior

By default, `sshIsolation` is set to `vpn`, which means:

- ✅ VPN users can SSH to any service
- ✅ **Web Terminal is always accessible** (unaffected by isolation settings)
- ❌ Services cannot SSH to each other

*This configuration maintains maximum security for production environments.*

### Configuring SSH Isolation

SSH isolation can be configured at two levels:

#### Project-Level Configuration

Set the `sshIsolation` project variable through:
- **GUI**: Navigate to **Project Environment Variables**
- **Import**: Add to your `import.yaml`:

```yaml title="import.yaml"
project:
  sshIsolation: "vpn project"
```

#### Service-Level Override

Individual services can override the project setting:

```yaml title="import.yaml"
services:
  - hostname: api
    sshIsolation: "vpn service@admin"
```

:::note
In import YAML, `sshIsolation` can be also defined in `envVariables`/`envSecrets`.  (If both are present, the nested version takes precedence).
:::

### Isolation Modes

#### Rule Types

**Allow Rules**: Grant SSH access
- `vpn` *(default)* - VPN SSH connections
- `project` - Any service in the project
- `service` - Containers within the same service
- `service@name` - Specific service named "name"

**Block Rules**: Deny SSH access (use `-` prefix)
- `-vpn` - Block VPN SSH connections
- `-project` - Block all services
- `-service` - Block all services
- `-service@name` - Block specific service named "name"

:::info
**Web Terminal access is never blocked** by these rules and remains available as an emergency access method.
:::

### Combining Rules

You can combine multiple rules using spaces. The system evaluates rules by checking the most specific matches first.

#### Rule Evaluation Order

The system checks SSH connection rules in this priority:
1. **Specific service rules**: `service@name` or `-service@name`
2. **General service rules**: `service` or `-service`
3. **Project rules**: `project` or `-project`
4. **VPN rules**: `vpn` or `-vpn`

:::note Important
- Block rules (`-`) always take priority over allow rules when both apply to the same source
- **Web Terminal access bypasses all these rules** and is always available
:::

When a service tries to connect, the system:

1. **Identifies the connecting source** (VPN user, Web Terminal, or specific service name)
2. **Checks for specific rules** first (like `service@admin` or `-service@api`)
3. **Falls back to general rules** (like `project` or `-service`)
4. **Allows or blocks** based on the first matching rule

#### Rule Evaluation Examples

</Dropdown>

#### Common Combinations

**Development Setup** *(ideal for microservices debugging)*:
```yaml
sshIsolation: "vpn project"
```
- ✅ VPN SSH connections can access all services
- ✅ Services can SSH to each other
- ✅ Web Terminal always accessible

**Gateway Pattern**:
```yaml
sshIsolation: "vpn service@gateway"
```
- ✅ VPN SSH connections can access all services
- ✅ Only the `gateway` service can SSH to other services
- ✅ Web Terminal always accessible
- ❌ Other services cannot SSH anywhere

**Selective Exclusion**:
```yaml
sshIsolation: "project -service@untrusted"
```
- ✅ All services can SSH to each other
- ✅ Web Terminal always accessible
- ❌ The `untrusted` service cannot SSH anywhere
- ❌ No VPN SSH access (not included in rules)

### Security Considerations

:::warning
Be careful with block rules - they can prevent expected SSH access even when allow rules are present.

**Example**: `project -service` would block all services from SSH, making the `project` rule ineffective for service-to-service connections.
:::

**Safety Mechanism**: Web Terminal access is never blocked by SSH isolation rules, ensuring you always have a way to access your containers for debugging or emergency fixes.

**Common Gotchas**:
- `service -service@api` blocks the `api` service from SSH but allows others within their own service
- `project -service` allows VPN SSH access but blocks all service-to-service SSH
- `-vpn -project -service` blocks all SSH connections but Web Terminal remains accessible
- Missing `vpn` in rules blocks VPN SSH access but Web Terminal still works

### Best Practices
- Start with `vpn` for production environments
- Use `vpn project` for development and debugging
- Test isolation changes in development environments first
- Be explicit about what you want to allow rather than relying on complex combinations
- Remember that Web Terminal provides emergency access when SSH rules are too restrictive
- Document your isolation strategy for team members

*Need help? Join our [Discord community](https://discord.gg/zeropsio).*