Serve the agent over HTTP

This page turns the SynapseX CLI into a local HTTP server so other tools — your own scripts, a browser UI, a second terminal — can drive the same agent. At the end you will have a server running on a port you chose, an OpenAPI document you fetched from it with curl, and the two environment variables that stop it from being open to anything on your network.

The concrete value: one running agent, shared between a terminal, a browser and your own tooling, instead of three disconnected copies.

Secure it before you expose it

With SYNAPSEX_CODE_SERVER_PASSWORD unset, the CLI prints Warning: SYNAPSEX_CODE_SERVER_PASSWORD is not set; server is unsecured. and the API is open to anything that can reach the port. On the default hostname (127.0.0.1) that means every process on your machine; if you change --hostname, it means your network.

Set both variables before starting a server you intend to reach from anywhere but your own shell:


export SYNAPSEX_CODE_SERVER_USERNAME=YOUR_SERVER_USERNAME
export SYNAPSEX_CODE_SERVER_PASSWORD=YOUR_SERVER_PASSWORD
synapsex-code serve --port 4399

Clients then authenticate with the matching flags:


synapsex-code attach http://127.0.0.1:4399 -u YOUR_SERVER_USERNAME -p YOUR_SERVER_PASSWORD

-u / --username and -p / --password exist on both attach and run, and default to SYNAPSEX_CODE_SERVER_USERNAME (falling back to synapsexCode) and SYNAPSEX_CODE_SERVER_PASSWORD.

Start a server


synapsex-code serve --port 4399


synapsexCode server listening on http://127.0.0.1:4399

Confirm it is really serving by fetching its OpenAPI document from another shell — this is a real result you can see immediately:


curl http://127.0.0.1:4399/doc

That returns the server’s OpenAPI 3.1.0 document, titled synapsexCode, which also tells you every route the running instance exposes.

Network options

Flag	Default	What it does
`--port <n>`	`0`	Port to listen on. `0` picks a random free port
`--hostname <host>`	`127.0.0.1`	Interface to bind
`--cors <domain...>`	(none)	Additional domains allowed for CORS
`--mdns`	off	Enable mDNS service discovery — this defaults the hostname to `0.0.0.0`
`--mdns-domain <name>`	`synapsexCode.local`	Custom mDNS domain

--mdns defaults the hostname to 0.0.0.0, which binds every interface. Only use it together with SYNAPSEX_CODE_SERVER_USERNAME and SYNAPSEX_CODE_SERVER_PASSWORD.

Open the web interface


synapsex-code web

This starts the same server and opens its browser UI. It accepts the same network options as serve, and prints the same unsecured warning when no password is set.

Attach a terminal to a running server


synapsex-code attach http://localhost:4096

attach connects an interactive terminal to a server that is already running, so you can drive an instance started elsewhere — in another shell, in a container, or on another machine you can reach.

Drive a running server from a script

run can target an existing server instead of starting its own:


synapsex-code run --attach http://localhost:4096 "summarise the open TODOs in src/"

Combine it with --format json when a script has to read the result. See Code with the SynapseX terminal agent.

Full flag list

Every serve, web, attach and run flag: CLI commands. Environment variables: CLI configuration.