Sidecar Server – start_server and stop_server

The sidecar server is a lightweight FastAPI+Uvicorn process that:

• Boots the services container (channels, LLM, RAG, artifacts, state store, etc.).
• Exposes a small HTTP/WebSocket API for adapters, web UI, and continuations.
• Installs a web channel so you can talk to agents via a browser.

For most applications without UI:

1. Call start_server(...) once at startup (or in a notebook cell).
2. Use @graph_fn, run_async, and context.* as usual.
3. Optionally call stop_server() in tests or when shutting down.

When using Aethergraph UI, it is suggested to

1. Use CLI aethergraph serve with your modules and scripts
2. Use --reload to auto reload changes when you make changes on graphs/agents

When using UI, you will need specific as_agent and as_app parameters in @graph_fn or @graphify; agents and apps are triggered from UI; you do not need to manually start the run in Python.

---

1. start_server – sync sidecar starter

start_server(*, workspace, host, port, log_level, ...)

Start (or reuse) the AetherGraph sidecar server in a normalized and flexible way.

This method manages server lifecycle, workspace locking, and dynamic loading of user code. It supports both in-process and cross-process server reuse, and can return handles for advanced control or integration.

Examples:

Basic usage to start a server and get its URL:

url = start_server(workspace="./aethergraph_data", port=0)

Loading user graphs before starting:

url = start_server(
  workspace="./aethergraph_data",
  port=0,
  load_paths=["./my_graphs.py"],
  project_root=".",
)

Starting and blocking until server exit (notebook/script mode):

url, handle = start_server(workspace="./aethergraph_data", port=0, return_handle=True)
print("Server running at", url)
try:
  handle.block()
except KeyboardInterrupt:
  print("Stopping server...")
  handle.stop()

Returning the dependency injection container for advanced use:

url, container = start_server(workspace="./aethergraph_data", return_container=True)

Returning both container and handle:

url, container, handle = start_server(
  workspace="./aethergraph_data",
  return_container=True,
  return_handle=True,
)

Parameters:

Name	Type	Description	Default
workspace	str	Persistent storage directory for server state and data.	'./aethergraph_data'
host	str	Host address to bind the server (default "127.0.0.1").	'127.0.0.1'
port	int	Port to bind the server (0 for auto-pick, or specify a fixed port).	8745
log_level	str	Logging level for the application.	'warning'
unvicorn_log_level	str	Logging level for the Uvicorn server.	'warning'
return_container	bool	If True, also return the app's dependency injection container.	False
return_handle	bool	If True, return a ServerHandle for programmatic control (block/stop).	False
load_modules	list[str] | None	List of Python modules to import before server start.	None
load_paths	list[str] | None	List of Python file paths to import before server start.	None
project_root	str | None	Path to add to sys.path for module resolution during loading.	None
strict_load	bool	If True, raise on import/load errors; otherwise, record errors in loader report.	False

Returns:

Name	Type	Description
str	str | tuple[str, Any] | tuple[str, ServerHandle] | tuple[str, Any, ServerHandle]	The server URL (e.g., "http://127.0.0.1:53421").
tuple	str | tuple[str, Any] | tuple[str, ServerHandle] | tuple[str, Any, ServerHandle]	Optionally, (url, container), (url, handle), or (url, container, handle) depending on the flags set and whether the server was started in-process.

Notes

• Workspace is a dedicated directory for server data, including logs, caches, and runtime state; multiple processes using the same workspace will coordinate to reuse a single server instance. Delete the workspace to reset state.
• Use handle.block() to wait for server exit when you need to keep the server running in a script or notebook. This is typically not needed when using the server in client mode.
• When you are using Aethergraph UI, use handle.block() to keep the server running so that the UI can connect to it and discover agents/apps.

---

2. start server via CLI

CLI start server

Start the AetherGraph server via CLI.

This entrypoint launches the persistent sidecar server for your workspace, enabling API access for frontend/UI clients. It supports automatic port selection, workspace isolation, and dynamic loading of user graphs/apps.

Examples:

Basic usage with default workspace and port:

python -m aethergraph serve --workspace # only default agents/apps show up

load user graphs from a file and autoreload on changes:

python -m aethergraph serve --load-path ./graphs.py --reload

Load multiple modules and set a custom project root:

python -m aethergraph serve --load-module mygraphs --project-root .

Reuse detection (print URL if already running):

python -m aethergraph serve --reuse

Customize workspace and port:

python -m aethergraph serve --workspace ./my_workspace --port 8000  # this will not show previous runs/artifacts unless reused

Parameters:

Name	Type	Description	Default
argv	list[str] | None	Optional list of CLI arguments. If None, uses sys.argv[1:].	None

Required keywords

• serve: Command to start the AetherGraph server. If no other command is given, the server will only load default built-in agents/apps.

Optional keywords

• workspace: Path to the workspace folder (default: ./aethergraph_data).
• host: Host address to bind (default: 127.0.0.1).
• port: Port to bind (default: 8745; use 0 for auto-pick).
• log-level: App log level (default: warning).
• uvicorn-log-level: Uvicorn log level (default: warning).
• project-root: Temporarily added to sys.path for local imports.
• load-module: Python module(s) to import before server starts (repeatable).
• load-path: Python file(s) to load before server starts (repeatable).
• strict-load: Raise error if graph loading fails.
• reuse: If server already running for workspace, print URL and exit.
• reload: Enable auto-reload (dev mode).

Returns:

Name	Type	Description
int	int	Exit code (0 for success, 2 for unknown command).

Notes

• Launching the server via CLI keeps it running persistently for API clients to connect like AetherGraph UI.
• In local mode, the server port will automatically be consistent with UI connections.
• use --reload for development to auto-restart on code changes. This will use uvicorn's reload feature.
• When switching ports, the UI will not show previous runs/artifacts unless the server is reused. This is because the server URL is tied to the frontend hash. Keep the server in a same port (default 8745) for local dev. Later the UI can support dynamic port discovery via server.json.