Environment Variables

ZestSSH supports per-connection environment variables that are automatically injected into the shell session when you connect. This is useful for setting PATH extensions, custom prompts, application-specific configuration, or any KEY=VALUE pair that your remote environment needs.

How It Works

Each saved connection has an envVars field stored as a JSON string in the database. When ZestSSH establishes an SSH session, it parses the JSON, validates each key, escapes each value, and sends export commands to the shell before the user sees the prompt.

The injection happens silently: the export commands are written to the shell followed by a clear command, so the user sees a clean terminal without the export lines cluttering the first screenful of output.

Setting Environment Variables

Open a connection’s edit screen and scroll to the Environment Variables section. Variables are entered as key-value pairs. Under the hood, they are serialized as a JSON object:

{
  "NODE_ENV": "production",
  "APP_PORT": "3000",
  "LOG_LEVEL": "debug",
  "CUSTOM_PATH": "/opt/myapp/bin"
}

You can add, edit, or remove variables from the connection editor. Changes take effect on the next connection — they do not apply to already-connected sessions.

Shell Injection Protection

Because environment variable names and values are injected directly into a shell command (export KEY='VALUE'), ZestSSH applies two layers of protection:

Key Validation

Every key is validated against the regex ^[a-zA-Z_][a-zA-Z0-9_]*$. This ensures keys:

• Start with a letter or underscore.
• Contain only letters, digits, and underscores.
• Cannot include shell metacharacters, spaces, or control characters.

Keys that fail validation are silently skipped and not injected.

Value Escaping

Values are wrapped in single quotes and any embedded single quotes are escaped using the standard shell idiom '\'' (end the single-quoted string, insert an escaped literal single quote, and start a new single-quoted string). This prevents shell expansion or command injection through values.

For example, a value like it's a "test" is injected as:

export MY_VAR='it'\''s a "test"'

This is safe because single-quoted strings in POSIX shells do not interpret any special characters except the closing quote itself.

Injection Sequence

When a connection is established, the injection runs in this order:

1. Parse the JSON string from the connection’s envVars field.
2. Iterate over each key-value pair.
3. Skip any key that fails the regex validation.
4. Escape single quotes in the value.
5. Append export KEY='escaped_value'; to a command buffer.
6. Append clear to the buffer to hide the export commands from the terminal.
7. Write the entire buffer to the shell as a single batch.

The process logs the count of successfully injected variables (e.g., “Injected 3 environment variable(s)”). If the JSON is malformed or empty, the injection is silently skipped.

Use Cases

• Application configuration: Set NODE_ENV, RAILS_ENV, FLASK_ENV, or similar application-mode variables so tools on the server behave correctly during your session.
• PATH extensions: Prepend custom binary directories: "PATH": "/opt/mytools/bin:$PATH" (note: since the value is single-quoted, the literal $PATH is injected; if you need shell expansion, use the startup command field instead).
• Per-server aliases: Set variables that your .bashrc conditionally reads to enable server-specific behavior.
• Credentials for CLI tools: Pass API tokens or configuration values needed by server-side scripts (the values are stored in the local SQLite database, not in secure storage — use the startup command field with source for secrets).

Cloud Sync

Environment variables are included in cloud sync exports. When you sync connections across devices, the envVars JSON is preserved for each connection.

Limitations

• Variables are injected via the shell’s stdin, not through the SSH protocol’s env channel. This means they work with any shell but may be visible in process listings briefly.
• If the remote shell does not support export (rare), the injection will fail silently.
• Shell expansion inside single-quoted values does not occur. If you need $HOME or $PATH expansion, use the startup command field instead.