smolvm env

Manage environment variables on a running VM

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

Code	Description
0	Success
1	Error occurred (connection failed, validation error, etc.)
2	Invalid 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