VoiceThere

Agent environment & secrets

Each project has two ways to pass configuration into the agent process that runs your uploaded bundle: environment variables (plain text) and secrets (encrypted). Both are set in the dashboard on the project overview and applied on the next deploy or session start.

Naming: use the AGENT_ prefix for both

Custom keys for your agent must use the AGENT_ prefix and match AGENT_[A-Z0-9_]+ (uppercase letters, digits, underscore). This applies to both plain variables and secrets — for example AGENT_GREETING or AGENT_OPENAI_API_KEY.

At runtime the platform merges plain variables and decrypted secrets into one environment map for your agent child process. Your code reads them like normal process.env.AGENT_* values.

Environment variables (plain)

  • Non-sensitive configuration — greetings, feature flags, model names, etc.
  • Values are visible in the dashboard after save (you can update or delete).
  • Up to 64 keys per project.

Secrets (encrypted)

  • API keys, tokens, and other credentials you do not want stored in plain text.
  • Write-once: after creation the plaintext value is never shown again — only a masked suffix (e.g. ••••a1b2).
  • To change a secret, delete it and create a new entry with the same name.
  • Up to 32 secrets per project.

Rules and reserved keys

  • A name cannot exist as both a plain variable and a secret — pick one storage type per key.
  • The platform sets its own keys for sessions and deploys (for example SESSION_ID, PROJECT_ID, BUILD_ID). Do not define those as AGENT_* entries.

When values take effect

Changes in the dashboard or CLI apply to new agent runs — promote or deploy an active build, or start a new voice session. Running sessions keep the environment they started with.

Where to configure

  • Dashboard: Project overview → Environment variables and Secrets panels.
  • CLI: voicethere projects environment and voicethere projects secrets — see examples below.
  • API: PUT /projects/:projectId/environment/:key and POST /projects/:projectId/secrets — see Control plane API.

CLI examples — environment variables

# List plain AGENT_* variables (values visible)
voicethere projects environment list

# View one key
voicethere projects environment view AGENT_GREETING

# Create or update (create and update are equivalent upserts)
voicethere projects environment create AGENT_GREETING "Hello from the CLI"
voicethere projects environment update AGENT_GREETING "Updated greeting"

# Delete
voicethere projects environment delete AGENT_GREETING

# Another project
voicethere projects environment list --project <project-uuid>

CLI examples — secrets

# List secrets (masked suffix only — plaintext never shown again)
voicethere projects secrets list

# Create (delete + recreate to change a value)
voicethere projects secrets create AGENT_OPENAI_API_KEY sk-...

# Delete before recreating with a new value
voicethere projects secrets delete AGENT_OPENAI_API_KEY

After changing env or secrets, run voicethere deploy --wait so new sessions pick up values.

Related

← All documentation