Add metadata field to instances for user-defined key-value pairs

Adds optional `metadata` map[string]string to instances, allowing callers
to attach arbitrary key-value metadata at creation time. Stored alongside
env vars in instance config and returned in GET /instances responses.
Updated domain types, API layer, generated OAPI types, and OpenAPI spec.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: rgarcia

cmd/api/api/instances.go

@@ -111,6 +111,11 @@ func (s *ApiService) CreateInstance(ctx context.Context, request oapi.CreateInst
 		env = *request.Body.Env
 	}
 
+	metadata := make(map[string]string)
+	if request.Body.Metadata != nil {
+		metadata = *request.Body.Metadata
+	}
+
 	// Parse network enabled (default: true)
 	networkEnabled := true
 	if request.Body.Network != nil && request.Body.Network.Enabled != nil {
@@ -216,6 +221,7 @@ func (s *ApiService) CreateInstance(ctx context.Context, request oapi.CreateInst
 		NetworkBandwidthDownload: networkBandwidthDownload,
 		NetworkBandwidthUpload:   networkBandwidthUpload,
 		Env:                      env,
+		Metadata:                 metadata,
 		NetworkEnabled:           networkEnabled,
 		Devices:                  deviceRefs,
 		Volumes:                  volumes,
@@ -666,6 +672,10 @@ func instanceToOAPI(inst instances.Instance) oapi.Instance {
 		oapiInst.Env = &inst.Env
 	}
 
+	if len(inst.Metadata) > 0 {
+		oapiInst.Metadata = &inst.Metadata
+	}
+
 	// Convert volume attachments
 	if len(inst.Volumes) > 0 {
 		oapiVolumes := make([]oapi.VolumeMount, len(inst.Volumes))

lib/instances/create.go

@@ -192,6 +192,9 @@ func (m *manager) createInstance(
 	if req.Env == nil {
 		req.Env = make(map[string]string)
 	}
+	if req.Metadata == nil {
+		req.Metadata = make(map[string]string)
+	}
 
 	// 7. Determine network based on NetworkEnabled flag
 	networkName := ""
@@ -298,6 +301,7 @@ func (m *manager) createInstance(
 		NetworkBandwidthUpload:   req.NetworkBandwidthUpload,   // Will be set by caller if using resource manager
 		DiskIOBps:                req.DiskIOBps,                // Will be set by caller if using resource manager
 		Env:                      req.Env,
+		Metadata:                 req.Metadata,
 		NetworkEnabled:           req.NetworkEnabled,
 		CreatedAt:                time.Now(),
 		StartedAt:                nil,

lib/instances/types.go

@@ -46,9 +46,10 @@ type StoredMetadata struct {
 
 	// Configuration
 	Env            map[string]string
-	NetworkEnabled bool   // Whether instance has networking enabled (uses default network)
-	IP             string // Assigned IP address (empty if NetworkEnabled=false)
-	MAC            string // Assigned MAC address (empty if NetworkEnabled=false)
+	Metadata       map[string]string // User-defined key-value metadata
+	NetworkEnabled bool              // Whether instance has networking enabled (uses default network)
+	IP             string            // Assigned IP address (empty if NetworkEnabled=false)
+	MAC            string            // Assigned MAC address (empty if NetworkEnabled=false)
 
 	// Attached volumes
 	Volumes []VolumeAttachment // Volumes attached to this instance
@@ -106,6 +107,7 @@ type CreateInstanceRequest struct {
 	NetworkBandwidthUpload   int64              // Upload rate limit bytes/sec (0 = auto, proportional to CPU)
 	DiskIOBps                int64              // Disk I/O rate limit bytes/sec (0 = auto, proportional to CPU)
 	Env                      map[string]string  // Optional environment variables
+	Metadata                 map[string]string  // Optional user-defined key-value metadata
 	NetworkEnabled           bool               // Whether to enable networking (uses default network)
 	Devices                  []string           // Device IDs or names to attach (GPU passthrough)
 	Volumes                  []VolumeAttachment // Volumes to attach at creation time

lib/oapi/oapi.go

@@ -144,6 +144,14 @@ components:
           example:
             PORT: "3000"
             NODE_ENV: production
+        metadata:
+          type: object
+          additionalProperties:
+            type: string
+          description: User-defined key-value metadata for the instance
+          example:
+            team: backend
+            purpose: staging
         network:
           type: object
           description: Network configuration for the instance
@@ -227,6 +235,11 @@ components:
           additionalProperties:
             type: string
           description: Environment variables
+        metadata:
+          type: object
+          additionalProperties:
+            type: string
+          description: User-defined key-value metadata
         network:
           type: object
           description: Network configuration of the instance