feat: support custom credential files via --auth-with

Allow passing credential file paths directly to --auth-with instead of only
accepting predefined auth methods. When a file path is detected (absolute,
relative, tilde-expanded, or *.json pattern), automatically mount it as the
agent's credential file with proper backup of existing credentials.

- Add is_file_path() and expand_and_validate_file() helpers for path detection
- Implement backup_credentials() to preserve existing creds before switching
- Support credentials-file auth method in both claude and codex agents
- Add workspace hashing and session tracking (~/config/deva/sessions/*.json)
- Attach Docker labels for workspace/auth/ephemeral tracking
- Export DEVA_AUTH_* environment variables into container for introspection
- Add 'status' management command to inspect running sessions
- Improve 'rm' command with --all flag and better container selection

Backward compatible: predefined auth methods still work as before.

Author: lroolle

.gitignore

@@ -1,6 +1,8 @@
 # Created by https://www.toptal.com/developers/gitignore/api/node
 # Edit at https://www.toptal.com/developers/gitignore?templates=node
 
+*.bak
+
 ### Node ###
 # Logs
 logs

Dockerfile

@@ -75,6 +75,9 @@ RUN --mount=type=cache,target=/root/.npm,sharing=locked \
 
 RUN curl -LsSf https://astral.sh/uv/install.sh | sh
 
+# Pre-install Python 3.14t (free-threaded) for uv
+RUN /root/.local/bin/uv python install 3.14t
+
 RUN --mount=type=cache,target=/tmp/go-cache,sharing=locked \
     ARCH=$(dpkg --print-architecture) && \
     GO_ARCH=$([ "$ARCH" = "amd64" ] && echo "amd64" || echo "arm64") && \
@@ -173,7 +176,7 @@ RUN --mount=type=cache,target=/home/deva/.npm,uid=${DEVA_UID},gid=${DEVA_GID},sh
     npm list -g --depth=0 @anthropic-ai/claude-code @openai/codex || true
 
 # Install Go tools for Atlassian integration (Confluence/Jira/Bitbucket)
-RUN go install github.com/lroolle/atlas-cli/cmd/atl@main && \
+RUN go install github.com/lroolle/atlas-cli/cmd/atl@5f6a20c4d164bf6fe6f5c60f9ac12dfccf210758 && \
     sudo mv $HOME/go/bin/atl /usr/local/bin/
 
 RUN git clone --depth=1 https://github.com/ohmyzsh/ohmyzsh "$DEVA_HOME/.oh-my-zsh" && \
@@ -187,6 +190,10 @@ RUN echo 'export ZSH="$HOME/.oh-my-zsh"' > "$DEVA_HOME/.zshrc" && \
     echo 'source $ZSH/oh-my-zsh.sh' >> "$DEVA_HOME/.zshrc" && \
     echo 'export PATH=$HOME/.local/bin:$HOME/.npm-global/bin:$HOME/go/bin:/usr/local/go/bin:$PATH' >> "$DEVA_HOME/.zshrc"
 
+# Pre-install uv for deva user and warm Python 3.14t
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh && \
+    $DEVA_HOME/.local/bin/uv python install 3.14t
+
 USER root
 
 COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh

agents/claude.sh

@@ -41,17 +41,32 @@ setup_claude_auth() {
 
     case "$method" in
         claude)
+            AUTH_DETAILS="claude-app-oauth (~/.claude)"
             ;;
         api-key)
-            validate_anthropic_key || auth_error "ANTHROPIC_API_KEY not set for --auth-with api-key" \
-                                                  "Set: export ANTHROPIC_API_KEY=your_api_key"
-            DOCKER_ARGS+=("-e" "ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY")
+            # Auto-detect OAuth token vs regular API key
+            if [ -n "${CLAUDE_CODE_OAUTH_TOKEN:-}" ]; then
+                DOCKER_ARGS+=("-e" "CLAUDE_CODE_OAUTH_TOKEN=$CLAUDE_CODE_OAUTH_TOKEN")
+                AUTH_DETAILS="oauth-token (CLAUDE_CODE_OAUTH_TOKEN)"
+                echo "Using OAuth token from CLAUDE_CODE_OAUTH_TOKEN" >&2
+            elif [ -n "${ANTHROPIC_API_KEY:-}" ] && is_oauth_token_pattern "$ANTHROPIC_API_KEY"; then
+                DOCKER_ARGS+=("-e" "CLAUDE_CODE_OAUTH_TOKEN=$ANTHROPIC_API_KEY")
+                AUTH_DETAILS="oauth-token (auto-detected from ANTHROPIC_API_KEY)"
+                echo "Detected OAuth token in ANTHROPIC_API_KEY, using as CLAUDE_CODE_OAUTH_TOKEN" >&2
+            elif [ -n "${ANTHROPIC_API_KEY:-}" ]; then
+                DOCKER_ARGS+=("-e" "ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY")
+                AUTH_DETAILS="api-key (ANTHROPIC_API_KEY)"
+            else
+                auth_error "No API key found for --auth-with api-key" \
+                           "Set: export ANTHROPIC_API_KEY=sk-ant-... or export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-..."
+            fi
             ;;
         copilot)
             validate_github_token || auth_error "No GitHub token found for copilot auth" \
                                                 "Run: copilot-api auth, or set GH_TOKEN=\$(gh auth token)"
             start_copilot_proxy
 
+            AUTH_DETAILS="github-copilot (proxy port $COPILOT_PROXY_PORT)"
             DOCKER_ARGS+=("-e" "ANTHROPIC_BASE_URL=http://$COPILOT_HOST_MAPPING:$COPILOT_PROXY_PORT")
             DOCKER_ARGS+=("-e" "ANTHROPIC_API_KEY=dummy")
 
@@ -74,9 +89,11 @@ setup_claude_auth() {
                 auth_error "CLAUDE_CODE_OAUTH_TOKEN not set for --auth-with oat" \
                            "Set: export CLAUDE_CODE_OAUTH_TOKEN=your_token"
             fi
+            AUTH_DETAILS="oauth-token (CLAUDE_CODE_OAUTH_TOKEN)"
             DOCKER_ARGS+=("-e" "CLAUDE_CODE_OAUTH_TOKEN=$CLAUDE_CODE_OAUTH_TOKEN")
             ;;
         bedrock)
+            AUTH_DETAILS="aws-bedrock (region: ${AWS_REGION:-default})"
             DOCKER_ARGS+=("-e" "CLAUDE_CODE_USE_BEDROCK=1")
             if [ -d "$HOME/.aws" ]; then
                 DOCKER_ARGS+=("-v" "$HOME/.aws:/home/deva/.aws:ro")
@@ -95,6 +112,7 @@ setup_claude_auth() {
             fi
             ;;
         vertex)
+            AUTH_DETAILS="google-vertex (gcloud)"
             DOCKER_ARGS+=("-e" "CLAUDE_CODE_USE_VERTEX=1")
             if [ -d "$HOME/.config/gcloud" ]; then
                 DOCKER_ARGS+=("-v" "$HOME/.config/gcloud:/home/deva/.config/gcloud:ro")
@@ -104,6 +122,15 @@ setup_claude_auth() {
                 DOCKER_ARGS+=("-e" "GOOGLE_APPLICATION_CREDENTIALS=$GOOGLE_APPLICATION_CREDENTIALS")
             fi
             ;;
+        credentials-file)
+            if [ -z "${CUSTOM_CREDENTIALS_FILE:-}" ]; then
+                auth_error "CUSTOM_CREDENTIALS_FILE not set for credentials-file auth"
+            fi
+            AUTH_DETAILS="credentials-file ($CUSTOM_CREDENTIALS_FILE)"
+            backup_credentials "claude" "${CONFIG_ROOT:-}" "$CUSTOM_CREDENTIALS_FILE"
+            DOCKER_ARGS+=("-v" "$CUSTOM_CREDENTIALS_FILE:/home/deva/.claude/.credentials.json")
+            echo "Using custom credentials: $CUSTOM_CREDENTIALS_FILE -> /home/deva/.claude/.credentials.json" >&2
+            ;;
         *)
             auth_error "auth method '$method' not implemented"
             ;;

agents/codex.sh

@@ -61,17 +61,20 @@ setup_codex_auth() {
 
     case "$method" in
         chatgpt)
+            AUTH_DETAILS="chatgpt-oauth (~/.codex)"
             ;;
         api-key)
             validate_openai_key || auth_error "OPENAI_API_KEY not set for --auth-with api-key" \
                                               "Set: export OPENAI_API_KEY=your_api_key"
+            AUTH_DETAILS="api-key (OPENAI_API_KEY)"
             DOCKER_ARGS+=("-e" "OPENAI_API_KEY=$OPENAI_API_KEY")
             ;;
         copilot)
             validate_github_token || auth_error "No GitHub token found for copilot auth" \
                                                 "Run: copilot-api auth, or set GH_TOKEN=\$(gh auth token)"
             start_copilot_proxy
 
+            AUTH_DETAILS="github-copilot (proxy port $COPILOT_PROXY_PORT)"
             DOCKER_ARGS+=("-e" "OPENAI_BASE_URL=http://$COPILOT_HOST_MAPPING:$COPILOT_PROXY_PORT")
             DOCKER_ARGS+=("-e" "OPENAI_API_KEY=dummy")
 
@@ -87,6 +90,15 @@ setup_codex_auth() {
             DOCKER_ARGS+=("-e" "NO_PROXY=${NO_PROXY:+$NO_PROXY,}$no_proxy")
             DOCKER_ARGS+=("-e" "no_grpc_proxy=${NO_GRPC_PROXY:+$NO_GRPC_PROXY,}$no_proxy")
             ;;
+        credentials-file)
+            if [ -z "${CUSTOM_CREDENTIALS_FILE:-}" ]; then
+                auth_error "CUSTOM_CREDENTIALS_FILE not set for credentials-file auth"
+            fi
+            AUTH_DETAILS="credentials-file ($CUSTOM_CREDENTIALS_FILE)"
+            backup_credentials "codex" "${CONFIG_ROOT:-}" "$CUSTOM_CREDENTIALS_FILE"
+            DOCKER_ARGS+=("-v" "$CUSTOM_CREDENTIALS_FILE:/home/deva/.codex/auth.json")
+            echo "Using custom credentials: $CUSTOM_CREDENTIALS_FILE -> /home/deva/.codex/auth.json" >&2
+            ;;
         *)
             auth_error "auth method '$method' not implemented"
             ;;

agents/shared_auth.sh

@@ -43,13 +43,22 @@ validate_github_token() {
 }
 
 validate_anthropic_key() {
-    [ -n "${ANTHROPIC_API_KEY:-}" ]
+    [ -n "${ANTHROPIC_API_KEY:-}" ] || [ -n "${CLAUDE_CODE_OAUTH_TOKEN:-}" ]
 }
 
 validate_openai_key() {
     [ -n "${OPENAI_API_KEY:-}" ]
 }
 
+# Detects OAuth token pattern in environment variables only
+# (not for inspecting credential file contents)
+# OAuth tokens: sk-ant-oat01-*
+# API keys: sk-ant-api03-*
+is_oauth_token_pattern() {
+    local key="$1"
+    [[ "$key" == sk-ant-oat01-* ]]
+}
+
 COPILOT_PROXY_PID=""
 COPILOT_PROXY_PORT="$COPILOT_DEFAULT_PORT"
 
@@ -212,6 +221,66 @@ convert_openai_model_alias() {
     esac
 }
 
+is_file_path() {
+    local arg="$1"
+    [[ "$arg" == /* ]] || [[ "$arg" == ~* ]] || [[ "$arg" == ./* ]] || [[ "$arg" == ../* ]] || [[ "$arg" == *.json ]]
+}
+
+expand_and_validate_file() {
+    local path="$1"
+    if [[ "$path" == ~* ]]; then
+        path="${path/#\~/$HOME}"
+    fi
+    if [ ! -f "$path" ]; then
+        auth_error "Credentials file not found: $path"
+    fi
+    if [[ "$path" == /* ]]; then
+        echo "$path"
+    else
+        echo "$(cd "$(dirname "$path")" && pwd)/$(basename "$path")"
+    fi
+}
+
+backup_credentials() {
+    local agent_name="$1"
+    local config_root="$2"
+    local source_file="${3:-}"  # Optional: file to compare against
+    local backup_path=""
+    local creds_file=""
+
+    case "$agent_name" in
+        claude)
+            if [ -n "$config_root" ] && [ -d "$config_root/claude/.claude" ]; then
+                creds_file="$config_root/claude/.claude/.credentials.json"
+            elif [ -d "$HOME/.claude" ]; then
+                creds_file="$HOME/.claude/.credentials.json"
+            fi
+            ;;
+        codex)
+            if [ -n "$config_root" ] && [ -d "$config_root/codex/.codex" ]; then
+                creds_file="$config_root/codex/.codex/auth.json"
+            elif [ -d "$HOME/.codex" ]; then
+                creds_file="$HOME/.codex/auth.json"
+            fi
+            ;;
+    esac
+
+    if [ -n "$creds_file" ] && [ -f "$creds_file" ]; then
+        # Compare with source file if provided (avoid duplicate backups)
+        if [ -n "$source_file" ] && [ -f "$source_file" ]; then
+            if cmp -s "$creds_file" "$source_file"; then
+                echo "Credentials file identical to source, skipping backup" >&2
+                return 0
+            fi
+        fi
+
+        backup_path="${creds_file}.backup-$(date +%Y%m%d-%H%M%S)"
+        echo "Backing up existing credentials: $creds_file -> $backup_path" >&2
+        cp "$creds_file" "$backup_path"
+        echo "To restore: mv $backup_path $creds_file" >&2
+    fi
+}
+
 parse_auth_args() {
     local agent_name="$1"
     shift
@@ -238,24 +307,30 @@ parse_auth_args() {
         case "${args[$i]}" in
             --auth-with)
                 if [ $((i + 1)) -ge ${#args[@]} ]; then
-                    auth_error "--auth-with requires a method"
+                    auth_error "--auth-with requires a method or file path"
                 fi
                 auth_method="${args[$((i + 1))]}"
 
-                local method_supported=false
-                local method
-                for method in "${supported_methods[@]}"; do
-                    if [ "$method" = "$auth_method" ]; then
-                        method_supported=true
-                        break
+                if is_file_path "$auth_method"; then
+                    # shellcheck disable=SC2034
+                    CUSTOM_CREDENTIALS_FILE=$(expand_and_validate_file "$auth_method")
+                    auth_method="credentials-file"
+                else
+                    local method_supported=false
+                    local method
+                    for method in "${supported_methods[@]}"; do
+                        if [ "$method" = "$auth_method" ]; then
+                            method_supported=true
+                            break
+                        fi
+                    done
+
+                    if [ "$method_supported" = false ]; then
+                        local supported_list
+                        supported_list=$(IFS=', '; echo "${supported_methods[*]}")
+                        auth_error "$agent_name agent doesn't support auth method '$auth_method'" \
+                                   "Supported: $supported_list, or provide a credentials file path"
                     fi
-                done
-
-                if [ "$method_supported" = false ]; then
-                    local supported_list
-                    supported_list=$(IFS=', '; echo "${supported_methods[*]}")
-                    auth_error "$agent_name agent doesn't support auth method '$auth_method'" \
-                               "Supported: $supported_list"
                 fi
 
                 i=$((i + 2))
@@ -278,4 +353,4 @@ parse_auth_args() {
     PARSED_AUTH_METHOD="$auth_method"
     # shellcheck disable=SC2034
     PARSED_REMAINING_ARGS=("${remaining_args[@]+"${remaining_args[@]}"}")
-}
+}