AxonX Studio

English · 简体中文

AxonX Studio is the browser workspace for AxonX, an agent-native quantitative research framework. It connects task submission, execution monitoring, workspace artifacts, research charts, and an Agent assistant to the same AxonX service.

Studio is a React and TypeScript frontend. The AxonX backend executes Tasks, manages files and sessions, and exposes Job APIs; research plugins supply the algorithms. Available tasks, APIs, and results depend on the selected execution machine and its installed plugins.

Features

The interface supports English and Simplified Chinese, light/dark themes, and saved browser preferences. Hash routes preserve the selected machine and resource, for example #local/task-defs/catalog/demo.

Install and start

Use an activated Python environment with Python 3.12+. Local Task execution is supported on macOS and Linux. Prebuilt Studio packages require no Node.js or frontend build.

pip install "axonx[studio]"
export AXONX_SERVICE_TOKEN='replace-with-your-local-service-token'
axonx start --service.host 127.0.0.1

Open http://127.0.0.1:1024/. In Settings → Local service token, enter the same token and apply it. Studio saves the token in browser local storage and sends it as a Bearer token on API requests. Use the same settings form to replace or clear it.

You can also place AXONX_SERVICE_TOKEN in a .env file in the directory where you start AxonX. The CLI loads this file automatically; existing environment variables take precedence. See example.env for optional provider settings.

If AxonX is already installed, add Studio separately:

pip install axonx-studio

Restart the service after installation. AxonX loads dist/ through the package's static_dir() function and serves the UI at / when service.web_enabled is enabled.

Run your first task

1. Keep the machine selector on Local, then open Submit task.
2. Choose the built-in demo Task under Native tasks.
3. Set X to 2, Y to 3, and leave Fail as False.
4. Click Submit run, then open Task management and select the run.
5. Inspect its status, steps, logs, configuration, and final output.

Leave Task Name empty to generate a name for each experiment. Reusing a fixed name replaces the directory of a finished run. Upstream relationships record lineage; the graph does not automatically execute dependent Tasks.

Optional research and Agent setup

• Research plugins: install axonx-alpha158 or axonx-alpha158-enhanced in the execution service's Python environment, then restart the service. Research views need completed runs with standard metadata.json and artifact outputs.
• Tushare downloads: configure AXONX_TUSHARE_TOKEN on the backend. Override AXONX_TUSHARE_BASE_URL only when using a compatible custom endpoint.
• Agent: configure the backend's CLAUDE_CODE_API_KEY, CLAUDE_CODE_BASE_URL, and CLAUDE_CODE_MODEL_NAME as needed for your provider. Ordinary Tasks can run without model credentials. Stopping an Agent turn does not cancel a Task it submitted.
• Remote machines: configure backend service targets, then select the target in Studio. The browser authenticates to the local service; the backend resolves remote addresses and credentials and forwards requests using target.

See research setup, Agent configuration, and remote machines.

npm distribution and static hosting

The npm package distributes the built frontend assets:

npm install @flowllm-ai/axonx-studio

Serve node_modules/@flowllm-ai/axonx-studio/dist/ with your static server. An AxonX backend is still required. The frontend uses origin-relative API URLs, so configure the same origin to proxy /health, /jobs, /files, /mcp, and /proxy to that backend. Preserve Authorization headers and SSE streaming for live logs and Agent responses. Hash routing does not require server routes for individual Studio pages.

For AxonX's built-in hosting, install the Python package instead.

Develop from source

The frontend toolchain requires Node.js 22.x ≥ 22.13.0, 24.x, or 26+, as declared in package.json. Run the following from the repository root to install the backend and development dependencies:

pip install -e '.[dev]'
export AXONX_SERVICE_TOKEN='replace-with-your-local-service-token'
axonx start --service.host 127.0.0.1

In another terminal:

cd axonx_studio
npm ci
npm run dev

Open http://localhost:4173/ and configure the service token for this browser origin. Vite provides hot updates and proxies API requests to http://127.0.0.1:1024 by default.

To use a different backend:

AXONX_DEV_SERVER=http://127.0.0.1:2048 npm run dev

Vite also reads .env files from the repository root. Restart Vite after changing AXONX_DEV_SERVER. This setting controls the development proxy; it does not configure the backend URL in a production build.

Build and install local assets

# From axonx_studio/
npm run build
cd ..
pip install ./axonx_studio

build runs TypeScript checks and writes the static site to dist/. Restart AxonX to serve the installed package. After frontend changes, rebuild and reinstall to update the packaged assets.

npm pack and npm publish run the prepack build automatically. Python packaging includes existing dist/ assets; build them before creating a Python distribution.

Code organization

Use axonx.invoke or feature API wrappers for Job calls. Requests use { arguments, target }; the client checks the Job response envelope and returns answer. Propagate the selected target and cancellation signals through feature APIs. Reuse the shared SSE parser for streaming calls.

To add a page, register its route in src/app/routes.ts, navigation in navigation.ts, and rendering in PageOutlet.tsx. Add user-facing strings to both locale files. See Studio development for extension guidance.

Troubleshooting

Workspace preview uses paths relative to the execution workspace. The /files API handles staged uploads and cleanup; retrieve complete artifacts from the execution machine's workspace. Deleting runs or workspace entries removes their data and does not rebuild downstream results.

Documentation and license

• Studio getting started
• Task management
• Research artifact contract
• SSE event protocol
• Contributing

Released under the Apache License 2.0.