Skip to main content

​
Synopsis

smolvm env set <vm_id> KEY=VALUE... [OPTIONS]
smolvm env unset <vm_id> KEY... [OPTIONS]
smolvm env list <vm_id> [OPTIONS]

​
Description

The env command group provides subcommands for managing environment variables on running VMs. Variables are persisted in /etc/profile.d/smolvm_env.sh and automatically loaded for new SSH sessions.
Environment variable changes apply to new SSH sessions. Existing sessions require running source /etc/profile.d/smolvm_env.sh to pick up changes.

​
Subcommands

​
set

Set one or more environment variables on a VM. Variables are merged with existing ones. 
smolvm env set <vm_id> KEY=VALUE [KEY=VALUE...] [OPTIONS]

​
Arguments

​
vm_id
string
required
VM identifier
​
pairs
string[]
required
One or more KEY=VALUE pairs to set

​
Options

​
--ssh-key
string
default:"~/.smolvm/keys/id_ed25519"
SSH private key path for connecting to the VM
​
--ssh-user
string
default:"root"
SSH user to connect as

​
Examples

Set a single variable: 
smolvm env set my-vm API_KEY=sk-1234567890
Output: 
✓ 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-vm \
  OPENAI_API_KEY=sk-abc123 \
  MODEL=gpt-4 \
  MAX_TOKENS=2000
Output: 
✓ Set 3 env var(s) on 'agent-vm': MAX_TOKENS, MODEL, OPENAI_API_KEY
  Note: Changes apply to new SSH sessions. In an existing session, run:
    source /etc/profile.d/smolvm_env.sh
Set variables with custom SSH credentials: 
smolvm env set my-vm APP_ENV=production \
  --ssh-key ~/.ssh/custom_key \
  --ssh-user ubuntu

​
unset

Remove one or more environment variables from a VM. 
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 for connecting to the VM
​
--ssh-user
string
default:"root"
SSH user to connect as

​
Examples

Remove a single variable: 
smolvm env unset my-vm API_KEY
Output: 
✓ 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-vm OPENAI_API_KEY MODEL MAX_TOKENS
Output: 
✓ Removed 3 env var(s) from 'agent-vm': MAX_TOKENS, MODEL, OPENAI_API_KEY
  Note: Changes apply to new SSH sessions. In an existing session, run:
    source /etc/profile.d/smolvm_env.sh
Attempt to remove non-existent variables: 
smolvm env unset my-vm DOES_NOT_EXIST
Output: 
No matching variables found on 'my-vm': DOES_NOT_EXIST

​
list

List all SmolVM-managed environment variables on a VM. 
smolvm env list <vm_id> [OPTIONS]

​
Arguments

​
vm_id
string
required
VM identifier

​
Options

​
--show-values
flag
default:"false"
Show variable values (masked by default for security)
​
--ssh-key
string
default:"~/.smolvm/keys/id_ed25519"
SSH private key path for connecting to the VM
​
--ssh-user
string
default:"root"
SSH user to connect as

​
Examples

List variables (values masked): 
smolvm env list my-vm
Output: 
Environment variables for 'my-vm':
  API_KEY=****
  DATABASE_URL=****
  SECRET_TOKEN=****
  (use --show-values to reveal)
List variables with values shown: 
smolvm env list my-vm --show-values
Output: 
Environment variables for 'my-vm':
  API_KEY=sk-1234567890
  DATABASE_URL=postgresql://user:pass@localhost/db
  SECRET_TOKEN=abc123xyz
List variables on VM with no managed environment: 
smolvm env list empty-vm
Output: 
No SmolVM-managed environment variables on 'empty-vm'.

​
Environment Variable Validation

When setting variables, keys must follow these rules:
  • Must not be empty
  • Must follow shell variable naming conventions
  • Values can be any string (including empty strings)
Invalid key examples: 
# Missing value separator
smolvm env set my-vm INVALID
# Error: malformed pair (expected KEY=VALUE): 'INVALID'

# Empty key
smolvm env set my-vm =value
# Error: empty key in pair: '=value'

​
Persistence

Environment variables are stored in /etc/profile.d/smolvm_env.sh on the VM. This file:
  • Is sourced automatically for new login shells
  • Persists across VM restarts (if using persistent storage)
  • Can be manually sourced in existing sessions: source /etc/profile.d/smolvm_env.sh

​
Exit Codes

CodeDescription
0Success
1Error occurred (connection failed, validation error, etc.)
2Invalid usage (missing subcommand, malformed arguments)

​
Common Workflows

​
Configure an AI agent with API credentials

# Set credentials
smolvm env set agent-001 \
  OPENAI_API_KEY=sk-... \
  ANTHROPIC_API_KEY=sk-ant-...

# Verify they're set
smolvm env list agent-001

# SSH in and start your agent
ssh root@$(smolvm ip agent-001)

​
Update database connection string

# Remove old database URL
smolvm env unset web-app DATABASE_URL

# Set new database URL
smolvm env set web-app DATABASE_URL=postgresql://newhost/db

​
Audit environment variables

# List all VMs and check their environment
for vm_id in $(smolvm list --format=json | jq -r '.[].vm_id'); do
  echo "=== $vm_id ==="
  smolvm env list "$vm_id" --show-values
  echo ""
done

​
Security Considerations

Environment variables are stored in plaintext on the VM filesystem. For sensitive credentials:
  • Use dedicated secret management systems when possible
  • Restrict VM access appropriately
  • Use smolvm env list (without --show-values) to avoid accidental credential exposure in logs
  • Consider rotating credentials regularly
Last modified on March 3, 2026