Chan in a browser

The chan binary carries the whole UI: the web apps are built into it, and any browser can show them. Chan Desktop is not needed, which makes this the way to use chan on a server, in a VM, or on a machine where you cannot install an app. There are two ways in:

• Serve one workspace with chan serve --standalone, in the foreground, for as long as the command runs.
• Run a devserver, a background service that keeps a library of terminals and workspaces running whether or not anyone is connected, and open its Computers screen in a browser.

Install the CLI on the machine as in Install on the host. On FreeBSD, which has fetch instead of curl, run fetch -o - https://chan.app/install.sh | sh. The Linux build is statically linked, so the same binary runs on any distribution. Check it with chan --version.

Serve a workspace

Any directory can be a workspace. Start with a new one in your home directory:

chan: first run on this workspace; the search index builds in the background after the URL below, so the editor and terminal are usable right away even on a large tree.
chan is ready:
http://127.0.0.1:8787/?t=Zr8mT2xQwN6vLb3HcY5dKp7sJf9aGe4u

The command creates notes if it does not exist, registers it as a workspace, starts the server on 127.0.0.1:8787, opens your default browser on the printed URL, and keeps running in the foreground until Ctrl+C. --standalone makes this command the server: without it, chan serve first looks for a running Chan Desktop or devserver of yours and hands the workspace to it, so a workspace is only ever served by one process.

• --port 9000 serves on another port.
• --no-browser only prints the URL, for a machine without a desktop.
• Inside a git repository, chan serve expects the repository root, because links, the graph, and search follow the project boundary. Add --here to serve a subdirectory anyway.

Work in the browser

The URL opens a workspace window: tiling panes with tabs, as on the desktop, inside a browser tab. The pane menu lists the built-in apps, and the command launcher is Ctrl+Alt+K in a browser on every OS. Open a terminal and try:

cs open opens the file in the editor, in the same window. Search is Cmd+Shift+S on macOS and Ctrl+Alt+S elsewhere, and chan workspace search hello queries the same index from the terminal.

The shells live in the server, not in the browser tab. Reload the page, or close it and open the URL again, and your terminals are still running with their scrollback. Open the same URL in a second browser window and both share the workspace as two participants of one session.

Serve from another machine

The server listens on the loopback address only. To use a workspace on a remote machine, forward a port over ssh from your computer:

Then run chan serve --standalone --no-browser ./notes in that ssh session and open the printed URL on your computer. If 8787 is taken on your side, forward another local port, such as -L 9901:127.0.0.1:8787, and change the port in the URL to match. The workspace stays up only while ssh and the command run; a devserver, below, keeps it up for good.

Stop and check

Ctrl+C in the terminal running chan serve stops the server and ends the workspace's terminals. Your files, the index, and the window layout stay, and serving the directory again picks up where you left off, with the same URL. From another shell, chan ps shows which workspaces are served, and by what:

STATE    BY                PID  READY       GEN      PASS       ACTION     INDEXER   QUEUE  WORKSPACE
served   standalone      41873  -           -        -          -          -             -  /home/user/notes

chan workspace ls lists every registered workspace, served or not, and chan workspace forget ~/notes removes one along with chan's data about it. Your files are never touched.

Under the hood: while it runs, the server indexes the workspace for search and the graph, watches the directory and pushes changes to every open window, hosts the sessions of the browsers attached to it, and runs extensions. Everything it derives lives under ~/.chan (or $CHAN_HOME), never inside your directory. design.md describes the server and the workspace.

A devserver is the same server run as a background service, hosting a library instead of one workspace: standalone terminals, each with a file browser and an editor over the machine's own files, and as many workspaces as you register. Start it as in Start the devserver, then print its URL:

Like the URL of chan serve, it carries the devserver's token, kept under ~/.chan and the same across restarts; chan devserver rotate-token replaces it. On a remote machine, forward a port over ssh as above, for example ssh -L 9901:127.0.0.1:8787 user@host, and open the URL with the port changed to 9901.

The Computers screen

The devserver's address opens the Computers screen. In a browser it shows one card, This machine, meaning the machine that runs the devserver, with New terminal and New workspace and two lists: Terminals, which holds Terminal Window 1 on a new devserver, and Workspaces. The desktop's carousel, its All windows and Add devserver cards, and Cmd+P belong to Chan Desktop.

Each window row has Open window, which opens the window in a new browser tab. If nothing opens, allow pop-ups for the page. A terminal window works on the whole machine: cs open ~ shows your home directory in its file browser, and cs upload and cs download move files between the devserver and the browser's computer. Search, the graph, the dashboard, and agent teams belong to a project, so they need a workspace window.

Add a workspace

In a devserver terminal, chan open registers a directory with the devserver instead of starting a server of its own:

chan: opened a window for /home/user/notes with local devserver on port 8787 (library /home/user/.chan, chan 0.126.0)

The workspace appears under Workspaces with a window ready to open; New workspace on the card does the same from the browser. A workspace row offers New window, New terminal window, and a power button that turns the workspace off and on. Off unmounts it: its index and windows are kept, its terminals end, and chan asks first when any are running.

Hide and show windows

Windows outlive the browser tabs that show them. Hide window (the eye on a window row) takes a window out of the way while its terminals keep running: its tab shows a cover saying it is hidden, and you can close the tab. Show window brings it back, in its old tab or a new one. Start a build or an agent, hide its window, and check on it from the Computers screen later, from this computer or another one.

When several browser pages show the same Computers screen, one is the session leader: only that page shows and hides windows. See Hand over workspace leadership.

To upgrade, run chan upgrade and then chan devserver restart. On Linux under systemd, terminals survive the restart; elsewhere a restart ends them, and workspaces, windows, and layouts come back.