Stage Env

POST /v1/vms/{vm_id}/stage-env

Stage secret environment variables into a running VM's shell env.

Values are SECRETS: they are shell-escaped and written straight into the VM's ~/.instavm/env.sh (sourced by the shell) and the live tmux server. They are NEVER logged, NEVER echoed back, and NEVER persisted to the DB — only the env_NAMES are recorded on the owning Session so the guest-claim flow can report staged_env_names. This handler must not log body.

Note: there is no request-body-logging middleware in this app (the audit middleware records method/path/status only, never the body — see app/main.py:audit_request_middleware), so nothing extra needs to be excluded; we simply never log the values here.

Authentication

Requires authentication via: OAuth2PasswordBearer.

Parameters

Name	In	Type	Required	Description	Constraints
vm_id	path	string	Yes
X-API-Key	header	string | null	No		nullable

Request Body

Required: Yes

application/json

Resolved schema:

{
  "properties": {
    "entries": {
      "items": {
        "properties": {
          "env_name": {
            "type": "string",
            "title": "Env Name"
          },
          "value": {
            "type": "string",
            "title": "Value"
          }
        },
        "type": "object",
        "required": [
          "env_name",
          "value"
        ],
        "title": "StageEnvEntry"
      },
      "type": "array",
      "title": "Entries"
    }
  },
  "type": "object",
  "required": [
    "entries"
  ],
  "title": "StageEnvRequest"
}

Field details:

Field	Type	Required	Description	Constraints
entries	array<object>	Yes
entries[]	object	Yes
entries[].env_name	string	Yes
entries[].value	string	Yes

Responses

200

Successful Response

application/json

Resolved schema:

{
  "properties": {
    "staged": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "Staged"
    }
  },
  "type": "object",
  "required": [
    "staged"
  ],
  "title": "StageEnvResponse"
}

Field details:

Field	Type	Required	Description	Constraints
staged	array<string>	Yes
staged[]	string	Yes

422

Validation Error

application/json

Resolved schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

Field details:

Field	Type	Required	Description	Constraints
detail	array<object>	No
detail[]	object	No
detail[].loc	array<string | integer>	No
detail[].loc[]	string | integer	No
detail[].msg	string	No
detail[].type	string	No