Skip to content

uisurf-agent

Configuration

haruiz/uisurf-agent

Configuration¶

The package reads configuration from environment variables and .env files through python-dotenv.

Provider Variables¶

Variable	Description
`UISURF_PROVIDER`	Registered provider name. Defaults to `gemini`.
`UISURF_MODEL_ID`	Provider-specific model id. Falls back to `MODEL_ID`.
`MODEL_ID`	Backward-compatible model id used by the built-in Gemini model.
`UISURF_PROVIDER_BASE_URL`	Optional provider-specific base URL. Falls back to `UISURF_MODEL_BASE_URL` or `MODEL_BASE_URL`.
`UISURF_MODEL_BASE_URL`	Backward-compatible provider base URL fallback.
`MODEL_BASE_URL`	Optional provider-specific base URL fallback.

UISURF_PROVIDER selects the provider implementation, such as gemini, openai, or ollama. UISURF_MODEL_ID selects the concrete model variant for that provider.

Agent Server Variables¶

Variable	Description
`AGENT_HOST`	Default bind host for A2A servers.
`BROWSER_AGENT_PORT`	Browser A2A server port. Defaults to `8001`.
`DESKTOP_AGENT_PORT`	Desktop A2A server port. Defaults to `8002`.
`MOBILE_AGENT_PORT`	Mobile A2A server port. Defaults to `8003`.
`BROWSER_AGENT_PUBLIC_URL`	Public URL advertised by the browser A2A server.
`DESKTOP_AGENT_PUBLIC_URL`	Public URL advertised by the desktop A2A server.
`MOBILE_AGENT_PUBLIC_URL`	Public URL advertised by the mobile A2A server.

Safety And Auto Mode¶

Variable	Description
`AUTO_MODE`	Automatically approve safety-gated A2A actions by default.
`BROWSER_AGENT_AUTO_MODE`	Browser A2A override for automatic safety approval.
`DESKTOP_AGENT_AUTO_MODE`	Desktop A2A override for automatic safety approval.
`MOBILE_AGENT_AUTO_MODE`	Mobile A2A override for automatic safety approval.

Interactive CLI runs use the --auto-mode flag or Python constructor argument. A2A servers read the environment variables above.

A2A Step Limits¶

Variable	Description
`BROWSER_AGENT_MAX_STEPS`	Maximum browser reasoning/action iterations in A2A mode. Defaults to `40`.
`DESKTOP_AGENT_MAX_STEPS`	Maximum desktop reasoning/action iterations in A2A mode. Defaults to `40`.
`MOBILE_AGENT_MAX_STEPS`	Maximum mobile reasoning/action iterations in A2A mode. Defaults to `40`.

Observation Variables¶

Variable	Description
`MAX_OBSERVATION_IMAGES`	Number of image-bearing history items that keep image payloads. Defaults to `2`.
`OBSERVATION_SCALE`	Default screenshot scale for agents. Must satisfy `0 < scale <= 1`.
`BROWSER_OBSERVATION_SCALE`	Browser-only screenshot scale override.
`DESKTOP_OBSERVATION_SCALE`	Desktop-only screenshot scale override.
`MOBILE_OBSERVATION_SCALE`	Mobile-only screenshot scale override.
`DESKTOP_OBSERVATION_DELAY_MS`	Delay before each desktop screenshot capture.
`MOBILE_OBSERVATION_DELAY_MS`	Delay before each mobile screenshot capture.

Screenshot scaling changes only the image sent to the model. Action coordinates still map to the full browser viewport, desktop resolution, or Android device resolution.

Thought Streaming¶

Variable	Description
`INCLUDE_THOUGHTS`	Global default for model thought streaming when supported.
`BROWSER_INCLUDE_THOUGHTS`	Browser-only thought streaming override.
`DESKTOP_INCLUDE_THOUGHTS`	Desktop-only thought streaming override.
`MOBILE_INCLUDE_THOUGHTS`	Mobile-only thought streaming override.

Browser Variables¶

Variable	Description
`BROWSER_FAST_MODE`	Speeds up browser settling by waiting less aggressively.
`BROWSER_CDP_URL`	Chromium DevTools Protocol URL used by `BrowserController` when connecting to an existing browser.

Mobile Variables¶

Variable	Description
`MOBILE_DEVICE_SERIAL`	Android device serial used by the mobile A2A server when `--mobile-serial` is omitted.
`MOBILE_AGENT_MAX_STEPS`	Maximum mobile reasoning/action iterations in A2A mode. Defaults to `40`.
`MOBILE_OBSERVATION_DELAY_MS`	Delay before each Android screenshot capture.
`MOBILE_OBSERVATION_SCALE`	Mobile-only screenshot scale override.
`MOBILE_INCLUDE_THOUGHTS`	Mobile-only thought streaming override.

The mobile CLI also accepts --mobile-serial to select a specific Android device serial. If omitted, MobileController uses the first authorized device reported by ADB.

Example `.env`¶

GEMINI_API_KEY=your_key_here
UISURF_PROVIDER=gemini
UISURF_MODEL_ID=gemini-3-flash-preview
AGENT_HOST=0.0.0.0
BROWSER_AGENT_PORT=8001
DESKTOP_AGENT_PORT=8002
MOBILE_AGENT_PORT=8003
BROWSER_AGENT_PUBLIC_URL=http://localhost:8001/
DESKTOP_AGENT_PUBLIC_URL=http://localhost:8002/
MOBILE_AGENT_PUBLIC_URL=http://localhost:8003/
MOBILE_DEVICE_SERIAL=5C060DLCR002MM
MOBILE_OBSERVATION_DELAY_MS=1500
BROWSER_FAST_MODE=true
AUTO_MODE=false
INCLUDE_THOUGHTS=false
MAX_OBSERVATION_IMAGES=2
OBSERVATION_SCALE=0.75