[BUG] AEnvironment not running locally

[Cenrax]

Checklist

• The error occurs when using our provided Docker image.
• I can consistently reproduce the bug across multiple trials or random seeds.
• If the error causes experiment abortion, I've verified that this error is the root
  cause, not a secondary error caused by peer workers.

Detailed Information

Describe the bug

When attempting to initialize an AEnvironment instance using the mini-terminal environment in local mode (with DUMMY_INSTANCE_IP set), the health check endpoint at http://localhost:8081/health returns a 401 Unauthorized error. The server requires HTTP Basic Authentication (WWW-Authenticate: Basic realm="Authorization Required"), but the SDK does not provide any authentication credentials in the health check requests.

The api_key parameter passed to the Environment() constructor is only used for the AEnv Scheduler client and is not propagated to the health check or function execution endpoints. This causes the initialization to fail indefinitely as the health check cannot pass authentication.

Expected behavior

When initializing an environment in local mode following the SDK guide, the environment should:

1. Successfully connect to the mini-terminal server at localhost:8081
2. Pass the health check without authentication errors
3. Return the list of available tools
4. Allow interactive command execution

Alternatively, if authentication is required:

• The SDK should accept authentication credentials and pass them to all HTTP requests (health checks, function calls, etc.)
• The documentation should clearly specify how to configure authentication for local development
• There should be an option to disable authentication for local/development environments

Full logs

20251223-23:25:28.679 aenv.environment INFO: [ENV:None] Initializing environment: mini-terminal@1.0.1
20251223-23:25:28.679 aenv.environment INFO: [ENV:test] Waiting for environment mini-terminal@1.0.1 to be healthy...
20251223-23:25:28.679 aenv.environment INFO: [ENV:test] check mini-terminal@1.0.1 health at round 0 with url: http://localhost:8081/health, last_check_result=
20251223-23:25:28.679 aenv.environment INFO: [ENV:test] Executing function in environment mini-terminal@1.0.1 with url=http://localhost:8081/health proxy_headers={'AEnvCore-MCPProxy-URL': 'http://localhost:8081', 'AEnvCore-EnvInstance-ID': 'test'}, timeout=3.0
20251223-23:25:28.689 aenv.environment ERROR: [ENV:test] Function 'http://localhost:8081/health' execution http request failed: Client error '401 Unauthorized' for url 'http://localhost:8081/health'
For more information check: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 | Server error: Unauthorized | Type: HTTPStatusError | Environment: mini-terminal@1.0.1 | Arguments: {} | Timeout: 3.0s | Function URL: http://localhost:8081/health

curl verification showing Basic Auth requirement:

$ curl -v http://localhost:8081/health
> GET /health HTTP/1.1
> Host: localhost:8081
> User-Agent: curl/8.7.1
> Accept: */*
> 
< HTTP/1.1 401 Unauthorized
< X-Powered-By: Express
< WWW-Authenticate: Basic realm="Authorization Required"
< Date: Tue, 23 Dec 2025 17:56:02 GMT
< Connection: keep-alive
< Keep-Alive: timeout=5
< Content-Length: 12
< 
Unauthorized

To Reproduce

Commit ID

Using aenvironment package version from pip (latest available)

Environment

Software:

• Python: 3.12.3
• OS: macOS
• Package: aenvironment (installed via pip)
• Environment: mini-terminal@1.0.1

Hardware:

• MacBook Pro

Script

Following the official SDK guide at: https://inclusionai.github.io/AEnvironment/guide/sdk.html

Test script (mini_terminal_test.py):

import asyncio
from aenv import Environment

async def main():
    # Create environment instance
    mini_terminal = Environment("mini-terminal@1.0.1", ttl="60m", api_key="your-api-key-here")

    try:
        # Get available tools list
        tools = await mini_terminal.list_tools()
        print("Successfully obtained tool list:", tools)
        assert tools is not None
    except Exception as e:
        print(
            "Test completed - environment created successfully, but tool list may be empty:",
            str(e),
        )

    # Interactive command execution
    while True:
        try:
            user_input = input(">>> ").strip()
            if user_input.lower() in ("exit", "quit"):
                print("Exiting interactive mode")
                break

            # Call remote tool to execute command
            result = await mini_terminal.call_tool(
                "mini-terminal@1.0.1/execute_command",
                {"command": user_input, "timeout": 5}
            )
            print("Execution result:\n", result)
            print("-" * 60)

        except KeyboardInterrupt:
            print("\nInterrupt detected, enter 'exit' to quit or continue input")
            await mini_terminal.release()
            print("Environment successfully released")

if __name__ == "__main__":
    asyncio.run(main())

Environment setup:

export DUMMY_INSTANCE_IP=http://localhost
python mini_terminal_test.py

Issue:
The script fails at the health check phase with 401 Unauthorized errors, preventing environment initialization.

Root Cause Analysis:

1. The mini-terminal server at localhost:8081 requires HTTP Basic Authentication
2. The SDK's Environment class accepts an api_key parameter but only passes it to the AEnvSchedulerClient
3. Health check requests (and other function calls) use self.proxy_headers which only contains proxy metadata, not authentication credentials
4. No mechanism exists to pass authentication credentials to the health endpoint or function endpoints

Suggested Fixes:

1. Add authentication header support to proxy_headers when api_key is provided
2. Support HTTP Basic Auth credentials in addition to API key
3. Provide configuration option to disable authentication for local development
4. Update documentation to clarify authentication requirements and setup

[JacksonMei]

Hi, thank you for reporting the issue, the API key is only used for tenant and rate limiting purposes, not for authentication.
To start the mini-terminal server, please check if port 8081 is occupied by any other application:

lsof -i :8081
# or
netstat -tuln | grep :8081

If you're running locally with aenv run, the following configuration will ensure smooth connection without authentication:

cd aenv/builtin-envs/mini-terminal
aenv run

and in another terminal window:

export DUMMY_INSTANCE_IP=http://localhost
cd aenv/builtin-envs/mini-terminal
python test/terminal_usage_test.py