smolvm env - SmolVM

Overview

The smolvm env command group allows you to set, unset, and list environment variables on running VMs. Variables are persisted in /etc/profile.d/smolvm_env.sh and automatically loaded in new SSH sessions.

Subcommands

set

Set one or more environment variables

unset

Remove environment variables

list

Display current environment variables

smolvm env set

Set or update environment variables on a VM.

Syntax

smolvm env set <vm_id> KEY=VALUE [KEY=VALUE ...] [options]

Arguments

vm_id

string

required

VM identifier to configure

pairs

string[]

required

One or more KEY=VALUE pairs to set. Keys must be valid shell variable names (alphanumeric and underscore, cannot start with a digit).

Options

--ssh-key

string

default:"~/.smolvm/keys/id_ed25519"

SSH private key path for authentication

--ssh-user

string

default:"root"

SSH user for connecting to the VM

Examples

Set a Single Variable

smolvm env set my-vm API_KEY=sk-1234567890

✓ Set 1 env var(s) on 'my-vm': API_KEY
  Note: Changes apply to new SSH sessions. In an existing session, run:
    source /etc/profile.d/smolvm_env.sh

Set Multiple Variables

smolvm env set agent-1 \
  DATABASE_URL=postgres://localhost/db \
  REDIS_URL=redis://localhost:6379 \
  LOG_LEVEL=debug

✓ Set 3 env var(s) on 'agent-1': DATABASE_URL, LOG_LEVEL, REDIS_URL
  Note: Changes apply to new SSH sessions. In an existing session, run:
    source /etc/profile.d/smolvm_env.sh

Use Custom SSH Configuration

smolvm env set production-vm API_KEY=secret \
  --ssh-user admin \
  --ssh-key ~/.ssh/production_key

Variable Validation

Keys must follow shell variable naming rules:

# Valid keys
smolvm env set my-vm API_KEY=value          # ✓
smolvm env set my-vm DATABASE_URL=value     # ✓
smolvm env set my-vm MY_VAR_123=value       # ✓

# Invalid keys
smolvm env set my-vm 123VAR=value           # ✗ Cannot start with digit
smolvm env set my-vm MY-VAR=value           # ✗ Hyphens not allowed
smolvm env set my-vm MY.VAR=value           # ✗ Dots not allowed

Errors are reported immediately:

smolvm env set my-vm 123VAR=value

Error: Invalid environment variable key: '123VAR'

Merging Behavior

Variables are merged with existing ones, not replaced:

# Set initial variables
smolvm env set my-vm FOO=1 BAR=2

# Add more variables (FOO and BAR remain)
smolvm env set my-vm BAZ=3

# Update existing variable
smolvm env set my-vm FOO=999

# List all
smolvm env list my-vm --show-values

Environment variables for 'my-vm':
  BAR=2
  BAZ=3
  FOO=999

smolvm env unset

Remove environment variables from a VM.

Syntax

smolvm env unset <vm_id> KEY [KEY ...] [options]

Arguments

vm_id

string

required

VM identifier

keys

string[]

required

One or more variable names to remove

Options

--ssh-key

string

default:"~/.smolvm/keys/id_ed25519"

SSH private key path

--ssh-user

string

default:"root"

SSH user

Examples

Remove a Single Variable

smolvm env unset my-vm API_KEY

✓ Removed 1 env var(s) from 'my-vm': API_KEY
  Note: Changes apply to new SSH sessions. In an existing session, run:
    source /etc/profile.d/smolvm_env.sh

Remove Multiple Variables

smolvm env unset agent-1 DATABASE_URL REDIS_URL LOG_LEVEL

✓ Removed 3 env var(s) from 'agent-1': DATABASE_URL, LOG_LEVEL, REDIS_URL
  Note: Changes apply to new SSH sessions. In an existing session, run:
    source /etc/profile.d/smolvm_env.sh

Variable Not Found

If you try to remove variables that don’t exist:

smolvm env unset my-vm NONEXISTENT_VAR

No matching variables found on 'my-vm': NONEXISTENT_VAR

smolvm env list

Display environment variables currently set on a VM.

Syntax

smolvm env list <vm_id> [options]

Arguments

vm_id

string

required

VM identifier

Options

--show-values

boolean

default:false

Show actual values instead of masking them with ****

--ssh-key

string

default:"~/.smolvm/keys/id_ed25519"

SSH private key path

--ssh-user

string

default:"root"

SSH user

Examples

List Variables (Masked)

By default, values are masked for security:

smolvm env list my-vm

Environment variables for 'my-vm':
  API_KEY=****
  DATABASE_URL=****
  LOG_LEVEL=****
  (use --show-values to reveal)

List Variables (Revealed)

smolvm env list my-vm --show-values

Environment variables for 'my-vm':
  API_KEY=sk-1234567890
  DATABASE_URL=postgres://localhost/db
  LOG_LEVEL=debug

No Variables Set

If the VM has no SmolVM-managed environment variables:

smolvm env list empty-vm

No SmolVM-managed environment variables on 'empty-vm'.

How It Works

Environment variables are managed through SmolVM’s SSH-based mechanism:

Storage: Variables are written to /etc/profile.d/smolvm_env.sh on the VM
Loading: The file is automatically sourced in new SSH sessions
Persistence: Variables survive VM restarts (as long as the rootfs is persistent)

File Format

The generated file looks like:

# /etc/profile.d/smolvm_env.sh
export API_KEY="sk-1234567890"
export DATABASE_URL="postgres://localhost/db"
export LOG_LEVEL="debug"

Reloading in Existing Sessions

After changing variables, they apply to new SSH sessions automatically. For existing sessions, reload manually:

source /etc/profile.d/smolvm_env.sh

SmolVM prints this reminder after every set or unset operation:

  Note: Changes apply to new SSH sessions. In an existing session, run:
    source /etc/profile.d/smolvm_env.sh

Exit Codes

0: Success
1: Error (VM not found, SSH failure, invalid key format, etc.)
2: Invalid usage (missing arguments, no subcommand specified)

Common Workflows

Configure API Credentials

# Set API keys for external services
smolvm env set agent-vm \
  OPENAI_API_KEY=sk-... \
  ANTHROPIC_API_KEY=sk-ant-... \
  GITHUB_TOKEN=ghp_...

# Verify (masked)
smolvm env list agent-vm

Manage Database Connections

# Development environment
smolvm env set dev-vm \
  DATABASE_URL=postgres://localhost/dev \
  REDIS_URL=redis://localhost:6379

# Production environment
smolvm env set prod-vm \
  DATABASE_URL=postgres://prod.example.com/db \
  REDIS_URL=redis://prod.example.com:6379

Toggle Debug Logging

# Enable debug logging
smolvm env set my-vm LOG_LEVEL=debug DEBUG=true

# Disable debug logging
smolvm env set my-vm LOG_LEVEL=info
smolvm env unset my-vm DEBUG

Rotate Secrets

# Update a secret
smolvm env set my-vm API_KEY=new-secret-key

# Verify it changed
smolvm env list my-vm --show-values | grep API_KEY

Security Considerations

Environment variables are stored in plaintext on the VM filesystem. For sensitive data, consider using a secrets manager and fetching values at runtime.

Best Practices

Avoid logging values: When using --show-values, be careful not to log output
Use minimal permissions: Only grant SSH access to trusted keys
Rotate secrets regularly: Update sensitive values periodically
Clean up: Use unset to remove variables you no longer need

Alternative Approaches

For highly sensitive data, consider:

Secrets managers: Use Vault, AWS Secrets Manager, etc.
Runtime fetching: Fetch secrets when needed instead of storing them
Encrypted files: Store encrypted configuration files and decrypt at runtime

Troubleshooting

VM Not Found

Error: VM 'nonexistent' not found in state database

Solution: Verify the VM ID:

# List all VMs
python -c "from smolvm.vm import SmolVMManager; print([v.vm_id for v in SmolVMManager().list_vms()])"

SSH Connection Failed

Error: Failed to connect to VM: Connection refused

Solution: Ensure the VM is running and SSH is accessible:

from smolvm import VM

vm = VM.from_id("my-vm")
print(vm.get_ip())  # Check IP is assigned
result = vm.run("echo test")  # Test SSH
print(result.stdout)

Permission Denied

Error: Permission denied (publickey)

Solution: Verify SSH key permissions and path:

# Check key exists
ls -l ~/.smolvm/keys/id_ed25519

# Ensure proper permissions
chmod 600 ~/.smolvm/keys/id_ed25519

# Use custom key if needed
smolvm env list my-vm --ssh-key /path/to/custom/key

Malformed Pair Error

Error: malformed pair (expected KEY=VALUE): 'MYVAR'

Solution: Ensure you use = to separate key and value:

# Wrong
smolvm env set my-vm MYVAR value

# Correct
smolvm env set my-vm MYVAR=value

Getting Started

Core Concepts

Guides

CLI Reference

Operations

​Overview

​Subcommands

set

unset

list

​smolvm env set

​Syntax

​Arguments

​Options

​Examples

​Set a Single Variable

​Set Multiple Variables

​Use Custom SSH Configuration

​Variable Validation

​Merging Behavior

​smolvm env unset

​Syntax

​Arguments

​Options

​Examples

​Remove a Single Variable

​Remove Multiple Variables

​Variable Not Found

​smolvm env list

​Syntax

​Arguments

​Options

​Examples

​List Variables (Masked)

​List Variables (Revealed)

​No Variables Set

​How It Works

​File Format

​Reloading in Existing Sessions

​Exit Codes

​Common Workflows

​Configure API Credentials

​Manage Database Connections

​Toggle Debug Logging

​Rotate Secrets

​Security Considerations

​Best Practices

​Alternative Approaches

​Troubleshooting

​VM Not Found

​SSH Connection Failed

​Permission Denied

​Malformed Pair Error

​See Also

Build docs developers (and LLMs) love

Overview

Subcommands

smolvm env set

Syntax

Arguments

Options

Examples

Set a Single Variable

Set Multiple Variables

Use Custom SSH Configuration

Variable Validation

Merging Behavior

smolvm env unset

Syntax

Arguments

Options

Examples

Remove a Single Variable

Remove Multiple Variables

Variable Not Found

smolvm env list

Syntax

Arguments

Options

Examples

List Variables (Masked)

List Variables (Revealed)

No Variables Set

How It Works

File Format

Reloading in Existing Sessions

Exit Codes

Common Workflows

Configure API Credentials

Manage Database Connections

Toggle Debug Logging

Rotate Secrets

Security Considerations

Best Practices

Alternative Approaches

Troubleshooting

VM Not Found

SSH Connection Failed

Permission Denied

Malformed Pair Error

See Also