Web — langstage¶
The web stage: a chat workspace for your LangGraph agent with real-time streaming, a workspace file browser, a task board for background work, scheduled runs, and a canvas for reports. React frontend, FastAPI backend.
Quickstart¶
pip install langstage
langstage run --demo # keyless echo agent
langstage run --agent my_agent.py:graph # your agent
langstage run --agent my_agent.py:graph --port 8080 --theme dark --title "My Agent"
With no --agent and no configured spec, langstage run uses a built-in default
agent, which needs pip install "langstage[deepagents]" and ANTHROPIC_API_KEY.
From Python:
from langstage import CoworkApp
app = CoworkApp(
agent=your_langgraph_agent, # any LangGraph CompiledGraph
workspace="./workspace",
title="My Agent",
)
app.run()
run_app(agent=..., workspace=...) is the one-line shorthand. In a Jupyter notebook
the same app.run() serves on a background thread and returns a handle right away,
so the kernel stays usable; call server.stop() when you're done. In a notebook the
kernel's working directory is left alone. In a script or from the CLI, run() makes
the workspace the process's working directory, so your agent's relative file writes
land where the file browser shows them.
Demo¶
langstage run -a langstage_core.demo.tools:graph): a tool call, a reasoning turn, the file browser, and a background task on the Board.What it looks like¶
write_todos calls.
Highlights¶
- Streaming chat with inline tool calls (arguments, results, duration, status).
- Reasoning from reasoning models, in a collapsed Thinking block above the answer.
- Starter prompts: one-click suggestion chips on the empty screen.
- History: reopen, continue or delete past conversations from any browser. See History.
- Rich inline content: HTML, Plotly, images, DataFrames, PDFs, JSON.
- Math: TeX in a reply or a Canvas note renders as math,
\( … \)inline and\[ … \]or$$ … $$as display. A single$is left alone, so "$5 and $10" stays money, and a formula that isn't valid TeX shows as written. KaTeX ships in the package (no CDN) and loads with the first formula. - Canvas panel, a persistent report surface. Opt in by attaching
CanvasMiddlewareto your agent. - File browser with a syntax-highlighted viewer and live change detection.
- File mentions: type
@in the chat to pick a workspace file, or drop a file on the chat to upload and mention it. See Mention files in the chat. - Task board for background work, and schedules on cron.
- Human-in-the-loop approval dialogs. See Human-in-the-loop.
- Slash commands:
/save-workflow,/create-workflow,/run-workflow. - Theming (light, dark, auto, or your own CSS), optional HTTP Basic Auth, custom branding.
Bring your own agent¶
Point --agent at any compiled LangGraph graph. Chat, tool calls, the file browser,
the task board and schedules work immediately. A few features light up when your
agent follows a convention:
| Feature | How to unlock it |
|---|---|
| Plan tab | The agent calls write_todos (the deepagents convention). |
| Rich inline content | A tool returns the display_inline shape. |
| Canvas tab | Attach langstage.middleware.CanvasMiddleware. |
| Agent self-delegation and agent-created schedules | Add the host tools: from langstage import LANGSTAGE_TOOLS, then tools=[*my_tools, *LANGSTAGE_TOOLS]. |
| Human-in-the-loop review | LangGraph interrupt(), or deepagents' interrupt_on=.... |
Checkpointer. If your graph has none, LangStage attaches one, and at server
start it is a durable SQLite saver at <workspace>/.langstage/checkpoints.db. So
conversation memory, interrupts and the task review gate work, and survive a
restart. A graph that compiles in its own checkpointer keeps it.
Mention files in the chat¶
Type @ in the chat input to pick a file or folder from the workspace. The list
narrows as you type: @sal finds data/sales.csv, and @q3 draft finds
reports/q3/draft.md. Arrow keys choose, Enter or Tab inserts, and Escape
closes it.
- From the file browser. The
@button on a file row, or Mention in chat in the right-click menu, inserts that path at the chat cursor. - Drop a file on the chat to upload it into the folder the Files tab shows and
mention it. The message isn't sent until you press Enter. An existing file is never
replaced; the upload is saved as
name (1).extinstead. - What the agent sees. A mention is plain text: the workspace-relative path in
backticks, such as
`data/sales.csv`. The file's contents aren't added to the message. Your agent runs with the workspace root as its working directory, so the path opens as written, with no agent changes. - Left out. The picker skips dot folders such as
.gitand.langstage, and the folders the file tree hides, such asnode_modulesand.venv. Mentions and dropping are off when the Files tab is hidden (--no-show-files) and in a read-only conversation.
Over REST, GET /api/files/search?q=sal&limit=50 returns the matching paths, best
first, and POST /api/files/upload?path=dir/&unique=true saves a copy under a new name
instead of replacing a file. The search never leaves the workspace and stops after
50,000 entries or one second, with truncated: true.
History¶
Every chat is saved in the checkpointer under its session id, so it outlives the page that started it. History, next to New in the header, lists those conversations newest first, titled by their first message.
- Reopen and continue. Click a conversation to bring back its messages, tool calls and reasoning. Your next message continues it on the same thread, with its earlier context. New starts a fresh conversation and leaves the current one in History.
- From any browser, after a restart. The list comes from the server, not from the browser's storage.
- One window at a time. One window reads a conversation's event stream, so a reply is never split between two. A conversation that is open in another window, or has a turn running, opens read-only: you see a copy that refreshes as it changes. A second tab of the same browser counts as another window. Continue here moves the conversation to the window you click it in, once no turn is running, and the window that had it becomes the read-only copy.
- A reload is the same window. Reloading the page, or a dropped connection coming back, carries on with the conversation. The page catches up from the server on load: a turn that was running shows as running and is complete when it ends, and an approval it was paused on is shown again.
- Paused on an approval. Reopening a conversation that was waiting on an approval shows the approval again, and answering it resumes the turn.
- Delete is permanent. The trash icon removes the conversation from the checkpointer after a confirmation. It is refused while a turn is running.
- Not restored: per-turn timings, token counts and the Plan tab's list start from zero in a reopened conversation.
- Not listed: task and schedule runs. Those are on the Board.
Your own checkpointer. History needs a checkpointer that can list threads
(alist) and, for delete, remove one (adelete_thread). LangGraph's SQLite, Postgres
and in-memory savers can. If yours can't list, the History button is hidden; if it
can't delete, the trash icon is hidden. langstage check prints a history line that
says which applies. With an in-memory checkpointer the list lasts until the server
stops.
Large databases. The server reads the checkpoint database once at startup, in the background, and lists the newest conversations first. On a 150 MB database with 300 threads that takes about 20 seconds, and turns run normally meanwhile. After that the list is served from memory.
Access. Anyone who can reach the server can read and delete every past conversation, as they can browse the workspace files. See Security.
Command-line tools¶
langstage check --agent my_agent.py:graph # static preflight: loads? what lights up?
langstage check --agent my_agent.py:graph --live # + one real turn; exit 1 if it errors
langstage check --agent my_agent.py:graph --json | jq -e '.loads and .checks.canvas.ok'
langstage chat --demo "hello" # one turn, reply on stdout, no server
langstage config # resolved config (also --json, --strict)
langstage init # a fully commented langstage.toml
- Without
--agent,checkandchatuse the same agentrunserves: the configured one (LANGSTAGE_AGENT_SPECor[agent] spec), or with nothing configured, the built-in default agent (which needs thedeepagentsextra). checkprints[ ok ]/[warn]lines for loading, the checkpointer, History, Canvas,write_todosand the host tools. The static checks need no key.chatadds the same per-message context the browser does (current time and the workspace path). Pass--no-contextfor a bare echo in scripts.config --strictexits1if anything in the config was ignored or degraded: a malformedlangstage.toml, a bad value, an unknown key. See Configuration.
Task board¶
The Board tab delegates work to background copies of your agent while you keep
chatting. There is no extra infrastructure: tasks live in a local SQLite file
(<workspace>/.langstage/tasks.db, so the board survives a restart) and run on an
in-process worker pool built on the core task engine.
- A task moves
queued → ongoing → review → done. Cancel or retry from any card; a retry picks up where the task stopped instead of starting over. - Click a card to live-tail the agent's full stream, answer a task paused for review (approve, reject, edit or respond, whichever the interrupt allows), or send a follow-up.
- The default agent can delegate to itself with five tools (
start_async_task,check_async_task,list_async_tasks,update_async_task,cancel_async_task). Give a custom agent the same withLANGSTAGE_TOOLS(orlangstage_core.tasks.TASK_TOOLSfor just the task tools). Spawned tasks link to their parent on the board. - Concurrency is
LANGSTAGE_TASK_CONCURRENCY(default 3). - Every task runs the agent the server started with.
POST /api/tasksrejects a non-nullagent_specwith 422 rather than load another module over HTTP.
Run one server process
The task claim and the worker pool are scoped to one process. Multiple uvicorn workers would run tasks twice.
Schedules¶
The Schedules tab runs a prompt on a cron expression, with presets for common cadences. Each fire enqueues a task on the board.
- Schedules persist. They are stored in the same SQLite file as the board and reloaded at startup. Fires missed while the server was down are not replayed; each schedule resumes at its next time.
- Cron is UTC.
0 9 * * *fires at 09:00 UTC, whatever the host's timezone, and the tab shows times in UTC. - No overlaps. If the previous fire's task is still queued, running or
awaiting review, the next automatic fire is skipped (the row says
skipped: previous run still …). Run now bypasses this. - Can't be paused. Delete a schedule and create it again later.
POST /api/crontakes exactlyname,cronandprompt; any other field, includingenabled, is rejected with 422.
REST API and OpenAPI¶
The backend is FastAPI, so it serves a complete, always-current OpenAPI schema for the whole REST surface (chat, files, canvas, cron, tasks, health):
| Route | What |
|---|---|
/docs |
Swagger UI: try every endpoint. |
/redoc |
ReDoc: a readable reference. |
/openapi.json |
The raw schema, for client generators. |
Chat streams over server-sent events: GET /api/stream?session_id=… plus
POST /api/chat. A session with no open stream and no running turn is dropped 60
seconds after its stream closes; reconnecting with the same session_id picks the
conversation back up from the checkpointer. Tasks are under /api/tasks, schedules
under /api/cron (not /api/schedules).
One connection reads a session's stream at a time: a second one gets 409, because two
readers would split a turn's frames between them. Pass client=<an id of yours> to
name the reader. A connection with the client of the current reader replaces it
(your own reconnect), and a connection that is replaced gets a last superseded
frame. POST /api/chat/complete with the session_id of a session that has an open
stream is 409 for the same reason.
Past conversations are under /api/conversations: GET lists them (limit,
offset), GET /api/conversations/{id} returns one as a transcript, and DELETE
removes it. To continue one from your own client, POST
/api/conversations/{id}/open, then attach GET /api/stream?session_id={id}; open
answers 409 while a turn is running in it or another client is attached. With
?takeover=true a client that merely has it open is made to let go, and only a
running turn is a 409.
Health. GET /api/health is liveness (always auth-exempt). GET
/api/health?ready=1 is readiness: 200 only if the agent is a runnable graph and the
task store is reachable, else 503. Use it for reverse proxies, Kubernetes and uptime
monitors.
Security¶
- Auth. Set
--auth-password(orLANGSTAGE_AUTH_PASSWORD) to put HTTP Basic Auth on every route except/api/health, including/docsand WebSocket upgrades. - Binding to the network. The default
localhostbind is reachable only from the same machine. If you bind a non-loopback host (--host 0.0.0.0) without a password, the whole REST surface, including every past conversation and the file browser's read, write and delete, is open to anyone on the network. LangStage prints a warning at startup but still starts. The safer option is to keeplocalhostand use an SSH tunnel. - Files. The file routes stay inside the workspace, including through symlinks.
CORS¶
Browsers on the same machine (localhost, 127.0.0.1, [::1] on any port) can
call the server by default, which covers a frontend dev server. To allow other
origins, list them:
LANGSTAGE_CORS_ORIGINS="https://app.example.com,https://admin.example.com" langstage run --agent my_agent.py:graph
or [server] cors_origins = ["https://app.example.com"] in langstage.toml. Listed
origins get credentialed access (cookies and Basic Auth). * allows any
origin, with credentials off. Preflight OPTIONS requests are answered before auth,
so this works with --auth-password set. langstage config shows the resolved
value.
Host names¶
Since 0.13.56, a server bound to a loopback address (the default localhost) answers
only to localhost, 127.0.0.1, [::1], *.localhost names and its bind host. A
request with any other Host header gets 403. This stops DNS rebinding, where a
website points its own name at 127.0.0.1 to reach your local server. Behind a reverse
proxy that forwards the public host name (Caddy and Traefik do by default), allow that
name:
or LANGSTAGE_ALLOWED_HOSTS="agent.example.com". *.example.org matches its
subdomains, and * turns the check off. nginx's plain proxy_pass sends
127.0.0.1:<port> and needs nothing. Servers bound to other addresses aren't checked.
Configuration¶
Precedence, highest first: Python args > CLI flags > LANGSTAGE_* env >
project langstage.toml > global ~/.langstage/config.toml > defaults. See
Configuration for how the layers work.
| Option | CLI flag | Env var | Default |
|---|---|---|---|
| Agent spec | --agent |
LANGSTAGE_AGENT_SPEC |
built-in default agent (needs [deepagents]) |
| Workspace | --workspace |
LANGSTAGE_WORKSPACE_ROOT |
. |
| Host | --host |
LANGSTAGE_HOST |
localhost |
| Port | --port |
LANGSTAGE_PORT |
8050 |
| Debug | --debug |
LANGSTAGE_DEBUG |
false |
| Title | --title |
LANGSTAGE_TITLE |
the agent's .name, or LangStage |
| Subtitle | --subtitle |
LANGSTAGE_SUBTITLE |
hidden |
| Welcome message | --welcome-message |
LANGSTAGE_WELCOME_MESSAGE |
empty |
| Theme | --theme |
LANGSTAGE_THEME |
auto |
| Agent name | --agent-name |
LANGSTAGE_AGENT_NAME |
the agent's .name, or Agent |
| Icon URL | --icon-url |
LANGSTAGE_ICON_URL |
none |
| Auth username | --auth-username |
LANGSTAGE_AUTH_USERNAME |
admin |
| Auth password | --auth-password |
LANGSTAGE_AUTH_PASSWORD |
none (auth off) |
| Workflow prompts | --save-workflow-prompt, --run-workflow-prompt, --create-workflow-prompt |
LANGSTAGE_SAVE_WORKFLOW_PROMPT, … |
built in |
| Custom CSS | --custom-css |
LANGSTAGE_CUSTOM_CSS |
none |
| Canvas tab | --show-canvas/--no-show-canvas |
LANGSTAGE_SHOW_CANVAS |
auto (on with CanvasMiddleware) |
| Files tab | --show-files/--no-show-files |
LANGSTAGE_SHOW_FILES |
on |
| Task concurrency | — | LANGSTAGE_TASK_CONCURRENCY |
3 |
| CORS origins | — | LANGSTAGE_CORS_ORIGINS |
loopback only |
| Allowed hosts | — | LANGSTAGE_ALLOWED_HOSTS |
loopback names only |
execute_python memory (MB, default agent) |
— | LANGSTAGE_CELL_MEMORY_LIMIT_MB |
512 |
langstage init writes every option into a commented langstage.toml with its
section and env var, so you never have to guess the nesting.
Custom CSS. The theme is CSS custom properties, so you can restyle it with a small file: