Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

Expose the Admin startup browser preference (#1091)

Ali Khokhardb9bee171263
diff --git a/README.md b/README.md
index 16b05b4d..b0f503f0 100644
--- a/README.md
+++ b/README.md
@@ -92,7 +92,8 @@ fcc-server
To print the installed Free Claude Code version without starting the server,
run `fcc-server --version`.
-Keep this process running. The startup log shows the Admin UI address:
+Keep this process running. By default, the Admin UI opens in your browser once
+the server is healthy. Its address is always shown in the startup log:
```text
INFO: Admin UI: http://127.0.0.1:8082/admin (local-only)
diff --git a/pyproject.toml b/pyproject.toml
index 4eadc121..72c39050 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "4.0.0"
+version = "4.1.0"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/src/free_claude_code/cli/entrypoints.py b/src/free_claude_code/cli/entrypoints.py
index fe4a028f..7f45c05b 100644
--- a/src/free_claude_code/cli/entrypoints.py
+++ b/src/free_claude_code/cli/entrypoints.py
@@ -44,11 +44,14 @@ def serve(argv: Sequence[str] | None = None) -> None:
_migrate_legacy_env_if_missing()
_migrate_config_env_keys()
settings = get_settings()
+ should_open_admin = (
+ settings.open_admin_browser and not opened_admin_browser
+ )
if not _run_supervised_server(
- settings, open_admin_browser=not opened_admin_browser
+ settings, open_admin_browser=should_open_admin
):
return
- opened_admin_browser = True
+ opened_admin_browser = opened_admin_browser or should_open_admin
get_settings.cache_clear()
except KeyboardInterrupt:
return
@@ -56,19 +59,9 @@ def serve(argv: Sequence[str] | None = None) -> None:
kill_all_best_effort()
-def _admin_browser_open_enabled() -> bool:
- """Whether to open /admin when the server becomes reachable (FCC_OPEN_BROWSER)."""
-
- raw = os.environ.get("FCC_OPEN_BROWSER", "true").strip().lower()
- return raw not in {"", "0", "false", "no"}
-
-
def _schedule_open_admin_browser(settings: Settings) -> None:
"""After /health succeeds, open the admin UI in the default browser (daemon thread)."""
- if not _admin_browser_open_enabled():
- return
-
admin_url = local_admin_url(settings)
proxy_root_url = local_proxy_root_url(settings)
diff --git a/src/free_claude_code/config/admin/manifest.py b/src/free_claude_code/config/admin/manifest.py
index 1c026a8d..d7b25c5a 100644
--- a/src/free_claude_code/config/admin/manifest.py
+++ b/src/free_claude_code/config/admin/manifest.py
@@ -236,6 +236,15 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
default="8082",
restart_required=True,
),
+ ConfigFieldSpec(
+ "FCC_OPEN_BROWSER",
+ "Open Admin on Startup",
+ "runtime",
+ "boolean",
+ settings_attr="open_admin_browser",
+ default="true",
+ description="Open the Admin UI after the next fcc-server launch becomes healthy.",
+ ),
ConfigFieldSpec(
"MESSAGING_PLATFORM",
"Messaging Platform",
diff --git a/src/free_claude_code/config/settings.py b/src/free_claude_code/config/settings.py
index 718349d0..b1b48b9a 100644
--- a/src/free_claude_code/config/settings.py
+++ b/src/free_claude_code/config/settings.py
@@ -274,6 +274,7 @@ class Settings(BaseSettings):
# ==================== Server ====================
host: str = "0.0.0.0"
port: int = 8082
+ open_admin_browser: bool = Field(default=True, validation_alias="FCC_OPEN_BROWSER")
# Optional server API key to protect endpoints (Anthropic-style)
# Set via env `ANTHROPIC_AUTH_TOKEN`. When empty, no auth is required.
anthropic_auth_token: str = Field(
diff --git a/tests/api/test_admin.py b/tests/api/test_admin.py
index add2d082..4238370e 100644
--- a/tests/api/test_admin.py
+++ b/tests/api/test_admin.py
@@ -36,6 +36,7 @@ def _clear_process_config(monkeypatch) -> None:
"SAMBANOVA_API_KEY",
"HOST",
"PORT",
+ "FCC_OPEN_BROWSER",
"VOICE_NOTE_ENABLED",
"WHISPER_DEVICE",
"LOG_FILE",
@@ -122,6 +123,7 @@ def test_admin_config_masks_secrets_and_exposes_manifest(monkeypatch, tmp_path):
assert "SAMBANOVA_API_KEY" in keys
assert "TELEGRAM_PROXY_URL" in keys
assert "CEREBRAS_API_KEY" in keys
+ assert "FCC_OPEN_BROWSER" in keys
assert "ZAI_BASE_URL" not in keys
assert "CLAUDE_WORKSPACE" not in keys
assert "CLAUDE_CLI_BIN" not in keys
@@ -136,6 +138,12 @@ def test_admin_config_masks_secrets_and_exposes_manifest(monkeypatch, tmp_path):
field for field in body["fields"] if field["key"] == "TELEGRAM_PROXY_URL"
)
assert telegram_proxy_field["secret"] is True
+ open_browser_field = next(
+ field for field in body["fields"] if field["key"] == "FCC_OPEN_BROWSER"
+ )
+ assert open_browser_field["type"] == "boolean"
+ assert open_browser_field["value"] == "true"
+ assert open_browser_field["restart_required"] is False
restart_required = {
field["key"] for field in body["fields"] if field["restart_required"] is True
}
@@ -168,6 +176,30 @@ def test_admin_config_preserves_managed_env_source_contract(monkeypatch, tmp_pat
assert model_field["locked"] is False
+def test_admin_apply_persists_open_browser_for_next_launch(monkeypatch, tmp_path):
+ _set_home(monkeypatch, tmp_path)
+ _clear_process_config(monkeypatch)
+ app = create_test_app()
+
+ response = _local_client(app).post(
+ "/admin/api/config/apply",
+ json={"values": {"FCC_OPEN_BROWSER": False}},
+ )
+
+ assert response.status_code == 200
+ body = response.json()
+ assert body["applied"] is True
+ assert body["pending_fields"] == []
+ assert body["restart"] == {
+ "required": False,
+ "automatic": False,
+ "admin_url": None,
+ "fields": [],
+ }
+ managed_env = tmp_path / ".fcc" / ".env"
+ assert "FCC_OPEN_BROWSER=false" in managed_env.read_text(encoding="utf-8")
+
+
def test_admin_apply_masks_telegram_proxy_credentials(monkeypatch, tmp_path):
_set_home(monkeypatch, tmp_path)
_clear_process_config(monkeypatch)
diff --git a/tests/cli/test_entrypoints.py b/tests/cli/test_entrypoints.py
index 2de74b29..581b4a35 100644
--- a/tests/cli/test_entrypoints.py
+++ b/tests/cli/test_entrypoints.py
@@ -18,12 +18,14 @@ def _launcher_settings(
*,
port: int = 8082,
token: str = "freecc",
+ open_admin_browser: bool = True,
) -> Settings:
return Settings.model_construct(
host="0.0.0.0",
port=port,
anthropic_auth_token=token,
model="nvidia_nim/test-model",
+ open_admin_browser=open_admin_browser,
)
@@ -221,11 +223,8 @@ def test_fcc_owned_entrypoints_report_version_without_side_effects(
side_effect.assert_not_called()
-def test_schedule_open_admin_browser_opens_when_health_ready(
- monkeypatch: pytest.MonkeyPatch,
-) -> None:
+def test_schedule_open_admin_browser_opens_when_health_ready() -> None:
"""Opening /admin runs after /health preflight succeeds."""
- monkeypatch.delenv("FCC_OPEN_BROWSER", raising=False)
from free_claude_code.cli import entrypoints
from free_claude_code.config.server_urls import local_admin_url
@@ -255,18 +254,23 @@ def test_schedule_open_admin_browser_opens_when_health_ready(
assert opened_urls == [local_admin_url(settings)]
-def test_schedule_open_admin_browser_skips_when_disabled(
- monkeypatch: pytest.MonkeyPatch,
-) -> None:
- monkeypatch.setenv("FCC_OPEN_BROWSER", "0")
+def test_serve_skips_admin_browser_when_setting_is_disabled() -> None:
from free_claude_code.cli import entrypoints
- settings = _launcher_settings()
+ settings = _launcher_settings(open_admin_browser=False)
+ get_settings = MagicMock(return_value=settings)
+ get_settings.cache_clear = MagicMock()
- with patch.object(entrypoints.threading, "Thread") as thread_cls:
- entrypoints._schedule_open_admin_browser(settings)
+ with (
+ patch.object(entrypoints, "get_settings", get_settings),
+ patch.object(
+ entrypoints, "_run_supervised_server", return_value=False
+ ) as run_server,
+ patch.object(entrypoints, "kill_all_best_effort"),
+ ):
+ entrypoints.serve()
- thread_cls.assert_not_called()
+ run_server.assert_called_once_with(settings, open_admin_browser=False)
def test_serve_supervisor_restarts_when_app_requests_restart() -> None:
@@ -306,12 +310,15 @@ def test_serve_supervisor_restarts_when_app_requests_restart() -> None:
patch.object(entrypoints.uvicorn, "Config", side_effect=fake_config),
patch.object(entrypoints.uvicorn, "Server", side_effect=FakeServer),
patch.object(entrypoints, "build_asgi_app", side_effect=build_asgi_app),
- patch.object(entrypoints, "_schedule_open_admin_browser"),
+ patch.object(
+ entrypoints, "_schedule_open_admin_browser"
+ ) as schedule_open_admin,
patch.object(entrypoints, "kill_all_best_effort") as kill_all,
):
entrypoints.serve()
assert len(servers) == 2
+ schedule_open_admin.assert_called_once_with(settings)
get_settings.cache_clear.assert_called_once()
kill_all.assert_called_once()
diff --git a/tests/config/test_config.py b/tests/config/test_config.py
index b848b5e1..85457a2e 100644
--- a/tests/config/test_config.py
+++ b/tests/config/test_config.py
@@ -55,6 +55,15 @@ class TestSettings:
assert settings.log_raw_sse_events is False
assert settings.debug_platform_edits is False
assert settings.debug_subagent_stack is False
+ assert settings.open_admin_browser is True
+
+ def test_open_admin_browser_loads_from_environment(self, monkeypatch):
+ from free_claude_code.config.settings import Settings
+
+ monkeypatch.setenv("FCC_OPEN_BROWSER", "false")
+ monkeypatch.setitem(Settings.model_config, "env_file", ())
+
+ assert Settings().open_admin_browser is False
def test_default_claude_workspace_uses_fcc_home(self, monkeypatch, tmp_path):
"""Unset CLAUDE_WORKSPACE stores agent data under the fixed path helper."""
diff --git a/uv.lock b/uv.lock
index 9586f2c3..09d4bf53 100644
--- a/uv.lock
+++ b/uv.lock
@@ -561,7 +561,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "4.0.0"
+version = "4.1.0"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },