xray-interactive is a context-aware terminal editor for creating and changing
Xray-core JSON configurations.
It displays the config as structured JSON, highlights the JSON container under
the cursor, and offers schema-aware actions for that container. The project is
currently focused on inbounds, outbounds, and routing, with guided support
for VLESS, Tunnel, SOCKS, HTTP, XHTTP, and REALITY.
Important
xray-interactive only works when the current working directory contains an
Xray-core binary named xray or xray.exe. This is a deliberate project
invariant: the program never searches PATH for Xray.
Read this section before changing the code.
xray_interactive/cli.pyis the entry point and command dispatcher.xray_interactive/model.pyowns JSON creation, traversal, mutation, and atomic persistence.xray_interactive/render.pyconverts JSON into terminal lines carrying structural JSON paths. It also lays out the wrapping action picker.xray_interactive/schema.pyis the declarative guided-editing layer: field specifications, context actions, and object templates live here.xray_interactive/tui.pyowns curses interaction and executes actions. Keep schema selection inschema.py; only put imperative mutations intui.py.xray_interactive/importer.pyparses VLESS share links into outbound JSON.xray_interactive/xray.pyis the only layer that invokes the local Xray binary.- The guided schema is not an independent Xray validator. Xray itself remains
the source of truth through
xray run -test -config .... - Unknown configuration areas must remain editable through custom JSON actions and raw block editing. Do not reject valid future Xray fields merely because they are absent from the guided schema.
- Preserve atomic writes and
.bakbehavior when changing persistence.
The most important data type is JsonPath, a tuple of object keys and array
indexes. Examples:
() # config root
("inbounds",) # all inbounds
("inbounds", 0) # one inbound
("inbounds", 0, "settings", "users") # its users arrayThe cursor does not directly select text. Every rendered line has a
container_path and, where applicable, a value_path. The selected container
controls both highlighting and the actions shown at the bottom of the terminal.
| Path | Responsibility | Change this when... |
|---|---|---|
xray_interactive/cli.py |
Arguments and top-level command flow | Adding a CLI command or flag |
xray_interactive/model.py |
Config template, JSON paths, load/save, tags | Changing persistence or generic JSON behavior |
xray_interactive/render.py |
Structural JSON rendering and action wrapping | Changing what is highlighted or how footer actions wrap |
xray_interactive/schema.py |
Field specs, context actions, templates | Adding a protocol, setting, or guided action |
xray_interactive/tui.py |
Keyboard input, prompts, mutations, undo/redo | Adding interaction or a new imperative action operation |
xray_interactive/importer.py |
VLESS URI parsing and mapping | Supporting another share-link field or scheme |
xray_interactive/xray.py |
Binary discovery and subprocess calls | Adding an Xray-backed operation |
tests/test_model.py |
Core model and local-binary invariant | Changing generic config behavior |
tests/test_schema.py |
Protocol templates and guided schema | Adding or changing supported config entities |
tests/test_importer.py |
Share-link mapping | Changing link import behavior |
tests/test_tui.py |
Pure TUI layout behavior | Changing action picker layout |
flowchart TD
A["xray-interactive CLI"] --> B["Require ./xray or ./xray.exe"]
B --> C{"Selected mode"}
C -->|create/edit| D["Load config into Python dict"]
D --> E["Render JSON with structural paths"]
E --> F["Resolve actions for selected path"]
F --> G["Apply mutation with undo snapshot"]
G --> E
G --> H["Atomic save plus .bak"]
C -->|import-link| I["Parse VLESS URI"]
I --> H
C -->|validate| J["Run local Xray config test"]
find_xray_binary() accepts only these paths:
<current directory>/xray
<current directory>/xray.exe
Do not replace this with shutil.which() or an implicit PATH lookup. UUID
generation, version reporting, and config validation must use this exact binary
and run with its directory as the subprocess working directory.
Prompt input is parsed as JSON when possible:
443 -> integer
true -> boolean
["http", "tls"] -> array
{"enabled": true} -> object
example.com -> unquoted string
The config root must remain a JSON object. Existing configs may contain fields outside the current guided scope, and those fields must be preserved.
save_config() writes through a temporary file followed by os.replace().
When replacing an existing config, it copies the previous saved version to
<config name>.bak. Changes to save behavior must keep interruption-safe writes
and the one-file backup unless the project explicitly changes this contract.
actions_for(config, path) suggests valid-looking fields based on context, but
it does not prove that the resulting config is complete or accepted by a
particular Xray version. The t key and --validate delegate validation to the
local binary.
The current guided scope is intentionally narrower than the complete Xray schema.
--create-config creates all high-level entities represented by
TOP_LEVEL_TEMPLATE, including routing, inbounds, and outbounds.
- VLESS, including users and UUID generation through
xray uuid - Tunnel (
protocol: "tunnel", formerly dokodemo-door) - SOCKS, including authentication users and UDP settings
- HTTP, including Basic Authentication users and transparent mode
- Common inbound fields such as
listen,port,settings,streamSettings,tag, andsniffing
SOCKS and HTTP default to 127.0.0.1 because neither protocol encrypts proxy
traffic and their primary intended use here is a local proxy.
- VLESS outbound creation
- VLESS share-link import
- XHTTP transport settings
- REALITY client settings
- Routing object fields
- Rule creation
- Guided routing rule fields
For unsupported or newly introduced Xray fields, use:
+ custom keyfor an object;+ JSON itemfor an array;Eto replace the selected block through$EDITOR.
These escape hatches are part of the compatibility strategy, not temporary debug features.
render_json() produces RenderLine records instead of plain strings:
@dataclass
class RenderLine:
text: str
container_path: JsonPath
value_path: JsonPath | None = NoneSelection behavior follows container nesting:
- Outside child blocks, the root object is selected.
- On the
inboundsarray, all inbounds are selected. - Inside one inbound, that inbound object is selected.
- Inside
settings,streamSettings,xhttpSettings, orrealitySettings, the corresponding deeper object is selected.
actions_for() receives the selected path and returns Action objects. The
action picker is recalculated on every draw. [ and ] or Ctrl+Left and
Ctrl+Right change action_index; Enter calls Editor.apply_action().
The picker is intentionally multiline. layout_action_lines() wraps complete
action labels and keeps the selected action visible when the terminal is too
short to show every row.
Most actions use one of these operation names:
| Operation | Behavior |
|---|---|
append_template |
Append a template from template_for() to an array |
set_field |
Prompt for and add a missing object field |
jump |
Move selection to another JSON path |
use_xhttp |
Set the transport method and create xhttpSettings |
enable_reality |
Set security and create context-specific REALITY settings |
generate_uuid |
Call the local Xray binary and place the returned UUID |
append_json |
Prompt for a raw JSON array item |
custom_key |
Prompt for an arbitrary object key and value |
If a new feature can be represented by an existing operation, add only schema
and template data. Add a new apply_action() branch only when new imperative
behavior is actually required.
- Add protocol settings specifications near the other
*_SETTINGSconstants inschema.py. - Add an action under the
("inbounds",)branch inactions_for(). - Add protocol-specific
settingsrouting inactions_for(). - Add a complete starter object to
template_for(). - Add nested collection actions, such as user templates, when required.
- Reuse an existing action operation when possible.
- Add template and contextual-action tests to
tests/test_schema.py. - Confirm the generated JSON with a real local Xray binary.
- Parse and normalize the field in
parse_vless_link(). - Map it into the correct Xray JSON object.
- Add the query key to
consumed; otherwise the importer will correctly report it as unmapped. - Keep malformed optional values as warnings when safe; reject links missing required connection data.
- Add a focused test to
tests/test_importer.py.
- Define the action in
schema.py. - Implement the operation in
Editor.apply_action(). - Call
self.mutate()before changing config data so undo/redo and dirty state remain correct. - Return the best path to select after the mutation.
- Set a concise user-visible status message.
Python 3.10 or newer is required. Windows installs windows-curses
automatically through the platform-specific dependency in pyproject.toml.
From the repository:
python -m pip install -e .On Unix-like systems, the source launcher may also be used directly:
chmod +x xray-interactiveThe runtime directory should look like this:
runtime-directory/
├── xray # xray.exe on Windows
└── config.json # created by the tool or supplied by the user
If installed with pip or pipx, the xray-interactive launcher may live
elsewhere. The shell's current directory must still contain the Xray binary.
Create config.json and open the editor:
xray-interactive --create-configOpen an existing config (--edit-config is also the default mode):
xray-interactive --edit-config
xray-interactiveImport a VLESS outbound:
xray-interactive --import-link 'vless://...'Import and immediately edit:
xray-interactive --import-link 'vless://...' --edit-after-importValidate using the local Xray binary:
xray-interactive --validateShow the local binary version:
xray-interactive --xray-versionUse another config filename:
xray-interactive --edit-config --config client.json--create-config refuses to overwrite an existing file unless --force is
provided.
| Key | Action |
|---|---|
Up / Down, k / j |
Move through rendered JSON |
PgUp / PgDn |
Move one terminal page |
Ctrl+Left / Ctrl+Right or square-brackets |
Select a context action |
[ / ] |
Portable fallback for selecting a context action |
Ctrl+Up |
Select the parent JSON container |
Enter |
Apply the selected action |
e |
Edit the scalar on the current line |
E |
Replace the selected block using $EDITOR |
d |
Delete the current value, block, or item |
u / Ctrl+R |
Undo / redo |
s |
Save atomically and update the backup |
t |
Save and validate through local Xray |
? |
Show help |
q / Esc |
Quit, confirming if changes are unsaved |
Some curses builds do not expose curses.define_key(). The editor therefore
also decodes common xterm-compatible Ctrl+Arrow escape sequences itself.
The importer currently maps:
type=tcportype=rawtostreamSettings.method = "raw";type=xhttportype=splithttptomethod = "xhttp";security=realityto REALITY client settings;sni,fp,pbk/publicKey/password,sid,spx, andpqv;- XHTTP
host,path,mode, and JSON-objectextra; - VLESS
encryptionandflow.
Unknown query parameters are not injected into config JSON. They are returned as warnings so the user can review unsupported link data.
Run the complete test suite from the repository root:
python -m unittest discover -vThe tests do not require a real Xray installation. The binary-discovery test creates a temporary executable. Manual validation of generated configuration still requires a compatible local Xray binary.
Before submitting a change:
- Run all tests.
- Add tests at the layer where behavior changed.
- Check that unsupported JSON still round-trips without data loss.
- Check undo/redo for new TUI mutations.
- Check action wrapping at a narrow terminal width.
- Validate generated config with a real Xray binary when schema output changes.
- Searching the operating system
PATHfor Xray - Reimplementing the complete Xray validation rules in Python
- Hiding or deleting unknown Xray configuration fields
- Supporting every inbound, outbound, or transport protocol in the guided UI
- Treating
tunnelandtunas the same protocol
tunnel is the port-mapping/transparent-proxy inbound formerly known as
dokodemo-door. Xray's tun protocol creates a TUN interface and is not currently
part of the guided schema.
- Top-level configuration
- Inbound object
- Outbound object
- Routing
- VLESS inbound
- Tunnel inbound
- SOCKS inbound
- HTTP inbound
- Transport configuration
- REALITY
- XHTTP discussion and reference
When documentation and a local Xray build disagree, use the target Xray version's validation output as the final compatibility check.