Skip to guide

The local runtime

Ask about this guide

Understand the server-backed path used by the visual workspaces and the dependencies it needs.

Updated 9 sections · Current source build

On this page · 9 sections

Start the agent server

The root start:server script launches the Python agent server. It expects the configured project environment. Run it from the repository root after completing the branch's setup instructions.

Agent server
pnpm start:server

Know which configuration belongs to the server

The server reads CODEBRAIN_MODEL for model identity and OLLAMA_URL for its inference endpoint. AROXA_PORT selects the local runtime port, whose current default is 9090. These are server settings; the Python CLI’s --url and --model flags configure a different entry point.

Choose the intended environment before starting the process. The launch script attempts to activate the configured Python environment, but a successful shell launch does not establish that dependencies, model weights and inference are all available. If you change a setting, restart only the process you own and check the effective configuration again.

Current server configuration
SettingPurpose
CODEBRAIN_MODELSelect the model identity requested from inference.
OLLAMA_URLSelect the model-service chat endpoint.
AROXA_PORTSelect the localhost runtime port; default 9090.
AROXA_RUNTIME_TOKENConfigure runtime authentication; never include its value in shared logs.

Inspect health before opening a task

The current server exposes /health on its local endpoint. Its response includes ok, ollamaReachable and modelLoaded, so a reachable HTTP process can still report that inference is not ready. Read those fields together instead of treating HTTP 200 as a complete readiness signal.

The command below is a local diagnostic request, not a public API integration example. Use your configured port if it differs, and follow your branch’s authentication requirements. Do not paste a real response containing private configuration into a public issue without reviewing it. A passing health response still does not verify a project task or its final changes.

Inspect local runtime health
curl --max-time 5 http://127.0.0.1:9090/health

Connect the intended interface

The web and desktop workspaces use the server-backed runtime. A running server is one dependency, not the entire setup: the interface must point at the intended runtime, and that runtime must be able to reach the configured model service.

Package-specific interface launch commands can change. Use the scripts and README for the package you are evaluating instead of assuming the Python CLI flags apply everywhere.

Match the interface, server and model service

A visual workspace depends on a chain of connections. The browser or desktop interface must reach the intended runtime; the runtime must reach the model service; the selected model must be available there. A failure at one connection should be diagnosed there, rather than addressed by changing unrelated interface code.

Browser origins and runtime authentication are additional boundaries. If the interface reports an origin or authorization error, inspect the configured values for that deployment. Do not disable those controls or expose the localhost server just to make a connection test pass. Keep the diagnostic local and record the exact failing layer.

Diagnose each connection separately
LayerUseful evidence
Interface → runtimeThe configured runtime URL and actual connection error.
Runtime → inferenceHealth reachability and the selected model’s availability.
Task → toolsRegistered capabilities, approval decisions and tool observations.

Keep development local

The development runtime uses a localhost endpoint. Keep it local unless you deliberately configure and review a different deployment. Exposing a development server is a separate security decision, not a routine step in this guide.

A local application can still send data to a remote model or connector. Inspect those settings before working with private repositories.

A run is more than a response

The runtime records state, tool observations, approval decisions and verification. The model proposes language and actions; that proposal is not the sole authority on what may run or what counts as complete.

Completion checks depend on the evidence collected. An incomplete test can leave an important behavior unverified even if the process itself succeeded.

Follow one operation through verification

For a first visual-interface task, ask for a focused inspection. Compare the request, the operation shown in the record and the observation returned. If a write is later authorized, review the resulting diff and run a check that exercises the intended behavior. Keep a rejected or skipped operation distinct from an executed one.

A verification result belongs to a particular run and environment. Reusing an old passing output after changing code can produce a false sense of completion. Record what was checked after the change, what failed and what remains untested. The runtime’s completion machinery helps organize that evidence; it does not replace your acceptance criteria.

Prepare a useful handoff without exposing the runtime

When handing a run to another person, share a redacted description of the environment, the requested task, the relevant observations and the remaining question. Mention the interface and runtime versions available to you. Do not send tokens, private prompts or a full repository merely because a screenshot is insufficient.

Stop a development process through the terminal or process manager that started it. Do not kill unrelated listeners to free a port. Before a fresh run, check whether the previous attempt changed files or left an operation in progress. Hosting a production runtime is a separate deployment and security task; these docs do not turn the local development server into a public service.

Search covers these 8 guides. Press Esc to close.
Documentation