Skip to content

Commit 4f9edf9

Browse files
michael-farahvercel[bot]
michael-farah
and
vercel[bot]
authored
feat: add JSON Schema for agent-browser config files (vercel-labs#1242)
* feat: add JSON Schema for agent-browser config files Adds agent-browser.schema.json describing all config options with types and descriptions. Enables IDE autocomplete and validation when referenced via $schema in agent-browser.json or ~/.agent-browser/config.json. README and docs site updated to document the schema reference. * fix(schema): use integer type for maxOutput to match usize deserialization Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com> --------- Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
1 parent 19808d0 commit 4f9edf9

File tree

3 files changed

+184
-0
lines changed

3 files changed

+184
-0
lines changed

‎README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -730,6 +730,15 @@ AGENT_BROWSER_CONFIG=./ci-config.json agent-browser open example.com
730730

731731
All options from the table above can be set in the config file using camelCase keys (e.g., `--executable-path` becomes `"executablePath"`, `--proxy-bypass` becomes `"proxyBypass"`). Unknown keys are ignored for forward compatibility.
732732

733+
A [JSON Schema](agent-browser.schema.json) is available for IDE autocomplete and validation. Add a `$schema` key to your config file to enable it:
734+
735+
```json
736+
{
737+
"$schema": "https://raw.githubusercontent.com/vercel-labs/agent-browser/main/agent-browser.schema.json",
738+
"headed": true
739+
}
740+
```
741+
733742
Boolean flags accept an optional `true`/`false` value to override config settings. For example, `--headed false` disables `"headed": true` from config. A bare `--headed` is equivalent to `--headed true`.
734743

735744
Auto-discovered config files that are missing are silently ignored. If `--config <path>` points to a missing or invalid file, agent-browser exits with an error. Extensions from user and project configs are merged (concatenated), not replaced.

‎agent-browser.schema.json‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
{
2+
"$schema": "http://json-schema.org/draft-07/schema#",
3+
"title": "Agent Browser Configuration",
4+
"description": "Configuration file for agent-browser (e.g., agent-browser.json or ~/.agent-browser/config.json)",
5+
"type": "object",
6+
"properties": {
7+
"headed": {
8+
"type": "boolean",
9+
"description": "Show browser window instead of running headless."
10+
},
11+
"json": {
12+
"type": "boolean",
13+
"description": "Output in JSON format."
14+
},
15+
"debug": {
16+
"type": "boolean",
17+
"description": "Enable debug output."
18+
},
19+
"session": {
20+
"type": "string",
21+
"description": "Session identifier."
22+
},
23+
"sessionName": {
24+
"type": "string",
25+
"description": "Auto-save/load state persistence name."
26+
},
27+
"executablePath": {
28+
"type": "string",
29+
"description": "Path to a custom browser executable."
30+
},
31+
"extensions": {
32+
"type": "array",
33+
"items": {
34+
"type": "string"
35+
},
36+
"description": "Paths to browser extensions. Extensions from user-level and project-level configs are concatenated."
37+
},
38+
"profile": {
39+
"type": "string",
40+
"description": "Path to the browser profile data directory."
41+
},
42+
"state": {
43+
"type": "string",
44+
"description": "Path to load/save browser state."
45+
},
46+
"proxy": {
47+
"type": "string",
48+
"description": "Proxy server URL (e.g., http://localhost:8080)."
49+
},
50+
"proxyBypass": {
51+
"type": "string",
52+
"description": "Comma-separated domains to bypass the proxy (e.g., localhost,*.internal.com)."
53+
},
54+
"args": {
55+
"type": "string",
56+
"description": "Additional comma-separated launch arguments for the browser."
57+
},
58+
"userAgent": {
59+
"type": "string",
60+
"description": "Custom User-Agent string."
61+
},
62+
"provider": {
63+
"type": "string",
64+
"description": "Provider to use, such as 'ios'."
65+
},
66+
"device": {
67+
"type": "string",
68+
"description": "Device name or identifier for emulation or providers (e.g., 'iPhone 16 Pro')."
69+
},
70+
"ignoreHttpsErrors": {
71+
"type": "boolean",
72+
"description": "Ignore HTTPS errors during navigation."
73+
},
74+
"allowFileAccess": {
75+
"type": "boolean",
76+
"description": "Allow file:// URLs to access local files."
77+
},
78+
"cdp": {
79+
"type": "string",
80+
"description": "Chrome DevTools Protocol endpoint URL."
81+
},
82+
"autoConnect": {
83+
"type": "boolean",
84+
"description": "Auto-discover and connect to a running Chrome instance."
85+
},
86+
"annotate": {
87+
"type": "boolean",
88+
"description": "Annotated screenshot with numbered element labels."
89+
},
90+
"colorScheme": {
91+
"type": "string",
92+
"enum": ["dark", "light", "no-preference"],
93+
"description": "Color scheme preference."
94+
},
95+
"downloadPath": {
96+
"type": "string",
97+
"description": "Default directory for browser downloads."
98+
},
99+
"contentBoundaries": {
100+
"type": "boolean",
101+
"description": "Wrap page output in boundary markers for LLM safety."
102+
},
103+
"maxOutput": {
104+
"type": "integer",
105+
"minimum": 0,
106+
"description": "Max characters for page output (truncates beyond limit)."
107+
},
108+
"allowedDomains": {
109+
"type": "array",
110+
"items": {
111+
"type": "string"
112+
},
113+
"description": "Allowed domain patterns (e.g., ['example.com', '*.example.com'])."
114+
},
115+
"actionPolicy": {
116+
"type": "string",
117+
"description": "Path to action policy JSON file."
118+
},
119+
"confirmActions": {
120+
"type": "string",
121+
"description": "Comma-separated action categories requiring confirmation."
122+
},
123+
"confirmInteractive": {
124+
"type": "boolean",
125+
"description": "Enable interactive confirmation prompts (auto-denies if stdin is not a TTY)."
126+
},
127+
"engine": {
128+
"type": "string",
129+
"enum": ["chrome", "lightpanda"],
130+
"default": "chrome",
131+
"description": "Browser engine to use."
132+
},
133+
"screenshotDir": {
134+
"type": "string",
135+
"description": "Default screenshot output directory."
136+
},
137+
"screenshotQuality": {
138+
"type": "integer",
139+
"minimum": 0,
140+
"maximum": 100,
141+
"description": "JPEG quality for screenshots (0-100)."
142+
},
143+
"screenshotFormat": {
144+
"type": "string",
145+
"enum": ["png", "jpeg"],
146+
"description": "Screenshot format."
147+
},
148+
"idleTimeout": {
149+
"type": "string",
150+
"description": "Auto-shutdown the daemon after N ms of inactivity (e.g., '60000')."
151+
},
152+
"model": {
153+
"type": "string",
154+
"description": "AI model for chat command (e.g., 'openai/gpt-4o')."
155+
},
156+
"noAutoDialog": {
157+
"type": "boolean",
158+
"description": "Disable automatic dismissal of alert/beforeunload dialogs."
159+
},
160+
"headers": {
161+
"type": "string",
162+
"description": "Custom HTTP headers supplied as a JSON-formatted string."
163+
}
164+
},
165+
"additionalProperties": true
166+
}

‎docs/src/app/configuration/page.mdx‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,15 @@ AGENT_BROWSER_CONFIG=./ci-config.json agent-browser open example.com
3939
}
4040
```
4141

42+
A [JSON Schema](https://github.com/vercel-labs/agent-browser/blob/main/agent-browser.schema.json) is available for IDE autocomplete and validation. Add a `$schema` key to your config file to enable it:
43+
44+
```json
45+
{
46+
"$schema": "https://raw.githubusercontent.com/vercel-labs/agent-browser/main/agent-browser.schema.json",
47+
"headed": true
48+
}
49+
```
50+
4251
## All Options
4352

4453
Every CLI flag can be set in the config file using its camelCase equivalent:

0 commit comments

Comments
 (0)