Cloudy Cloud Docs

Dashboard and app previews

The dashboard is a read-only web page on your own computer that shows your cloud agents and the messages between them and your session. To look at an app a cloud agent is running, use cloudy-cloud open.

The dashboard and cloudy-cloud open work for every main session (Claude Code, Codex, opencode, pi, free-pi) and every worker agent (Claude Code, pi, oh-my-pi, Codex, opencode), because they read the event log that the cloud tools write. The Model column shows the profile name for a worker on another agent.

Start the dashboard

cloudy-cloud dashboard

This prints a link and opens it in your browser. The page is served from 127.0.0.1 on port 4477, or on a free port if 4477 is taken. Press Ctrl+C in the terminal to stop it.

OptionWhat it does
--demoShows sample data, so you can look around before you have started any agents.
--port NUses port N (0 to 65535).
--no-openPrints the link without opening a browser.

What it shows

The page has two views, switched at the top: List and Fleet.

  • List has the boxes in a left column and the selected box in a detail pane. Workers started by a cloud coordinator are nested under it; use the arrow next to the coordinator, or the Left and Right arrow keys, to close or open them.
  • Fleet shows one tile per box, with its status, description, id and time since last activity, and a Workers of heading under each coordinator. Select a tile to open it in the List view.

In the Fleet view, boxes whose brief names a trunk branch (fleet/<topic>) get their own section above the groups. The section heading says how many of the workers' branches are merged into that trunk, and each tile says merged or not merged. The check runs git branch -r --merged origin/<trunk> in the folder where the dashboard runs, and is cached for about 30 seconds. If git cannot answer, the heading says merge status unknown. Other boxes are grouped as below.

Boxes are grouped as Needs you, Active and Finished.

  • Needs you: agents that are idle, and agents that failed today.
  • Active: agents that are queued, starting or running.
  • Finished: everything else.

The top bar counts running, starting, idle and failed agents and those finished today. The browser tab title shows the failed and idle counts.

The detail pane

Select a box to see:

  • Status, Model (or profile), Started, Role, Started by (this session, or the coordinator that started it) and the Machine.
  • Harness: the agent that runs the worker (claude, pi, omp, codex or opencode). It also shows as a tag on the box.
  • Autofix: for an agent started with autofix, the state (for example running, with the round and the most rounds) and a link to the pull request, taken from the progress and result lines. It is shown only when the agent's text has them.
  • MCP: the names of the MCP servers the subagent has, when it has any.
  • Branch: the cloudy-cloud/<id> branch, with the result of the last push (the commit hash, or "push failed"), and copy buttons.
  • Deletes: when the machine is expected to be deleted, for an agent that is still active or idle. For an idle agent this is 60 minutes after it went idle. For an active agent the dashboard shows 8 hours after it started. That is only an upper estimate: the server deletes a worker machine at its own deadline, 6 hours after it starts by default (CLOUDY_CLOUD_WORKER_HOURS, at most 24), which can be earlier.
  • Open app: for a running or idle agent, the command cloudy-cloud open <id> <port> with a copy button. See below.
  • Activity: a timeline of the task you sent, follow-up messages, and the agent's replies, with what the agent did between them. Each step has a time. The agent's text is a block. Each tool call shows its name and its input as sent, cut at 4 KB, with a Show all button. Each tool result is one line, in green or red, that you can expand. Retries and errors are highlighted. A Thinking step shows only its length unless CLOUDY_CLOUD_STREAM_THINKING=1 was set when the agent ran. Each turn ends with a footer of tokens, cost and duration. When an agent has more than one turn, a Turn selector picks which one to read.
  • Source badge: next to the timeline, it says where those steps came from and how old they are: live from machine with the seconds since the last read, from local log (a copy kept on this computer), cached copy (the machine is deleted), or unavailable with the reason.
  • Live tail: while the selected agent is working, the page reads new steps every 2 seconds and shows Working with the time of the last step. It stops when you select another box or the tab is hidden. Other boxes are not read.
  • Terminal (cloud coordinators only): a read-only copy of the coordinator's tmux session, refreshed every 3 seconds while the tab is open. To work in it, run cloudy-cloud coordinator attach <name>; the tab has a copy button for the command.

When something is wrong

  • Offline: the page cannot reach the dashboard server. It keeps the last list, shows the time of the last update, and retries every 3 seconds. If it has no list yet, it shows The dashboard cannot reach its server. Start the server again with cloudy-cloud dashboard and open the new link.
  • Old link: each run makes a new link. A link from an earlier run is refused: a page that is already open shows This link is from an earlier run, and a request without the right token gets the text This dashboard link is missing its access key, or it is from an earlier run. Open the newest link in your terminal, or run cloudy-cloud dashboard again.
  • Live machines unavailable: a banner appears if the Instabox machine list cannot be read, for example when INSTABOX_API_KEY is missing or invalid. Session history still shows.
  • No boxes yet: an empty list means you have not started an agent from a cloudy-cloud session.

What it cannot show

  • Sessions started before the event log existed. Their agents have no history. If the machine is still running, it appears as a machine with no messages and a note that it has no title.
  • Machines started before stream capture existed, and machines deleted before any copy was kept. The badge says unavailable and the timeline explains why, so it shows no tool calls. Only the messages in the session log appear.
  • A coordinator that is not running. While a cloud coordinator's machine is running, the dashboard reads that machine's own event log and shows its workers with their prompts and replies, even for workers whose machines are already deleted (they appear as stopped, with the source "coordinator-log"). It reads at most one part of that log every 10 seconds, and only while the page is open. Once the coordinator's machine is deleted, nothing more can be read from it, and its workers appear only as far as their own machines or earlier cached copies show.
  • A cloud coordinator's own messages. A cloud coordinator runs on its own machine, so its messages are not recorded on your computer. Its workers are listed under it, and the Terminal tab shows what is on its screen now, not its history. Nested coordinators log on their own machine too.
  • Queued agents. A queued agent is shown as starting.
  • Ended sessions. An agent from a session that has since ended is shown as stopped.

Security model

  • Local only. The server listens on 127.0.0.1. It answers only requests whose Host is localhost or 127.0.0.1.
  • Per-run token. Each run makes a random token that is part of the link. A request without it gets a 401.
  • Read-only. It accepts only GET and HEAD requests. It cannot start, message or stop an agent.
  • Keys stay out of the browser. The Instabox key is used only by the server. Error text is redacted before it is sent to the page.
  • The event log is private to you. The log is ~/.config/cloudy-cloud/events.jsonl (set CLOUDY_CLOUD_EVENTS to move it), in a folder with mode 700, with file mode 600. Exact secret values are removed, and key-shaped text such as sk-…, ghp_…, NAME_KEY=… and bearer tokens is redacted, before anything is written. Each text is cut at 20,000 characters.

Prompts and replies can contain your code, and redaction only catches key-shaped text. Treat the log as private. It is never rotated; delete the file to clear the history. The dashboard reads the newest 16 MB of it.

Reach an app running on an agent's machine

If an agent starts a dev server or a web app, you can view it from your own browser. The dashboard shows the command for each running agent in its Open app row. Replace <port> with the port the app uses.

Private tunnel

cloudy-cloud open AGENT_ID 3000

This forwards http://127.0.0.1:3000 on your computer to port 3000 on the agent's machine, until you press Ctrl-C. Use an agent id from cloud_agent_list (the <id> in branch cloudy-cloud/<id>), a machine name or a machine id. A coordinator's machine is named coord-NAME. To use a different local port, write LOCAL:REMOTE, for example 8080:3000. Only you can reach the tunnel.

Share a private link

cloudy-cloud open AGENT_ID 3000 --share

This prints a private link with a token in the URL. It never publishes the app publicly.

Anyone who has the link can open the app, until the machine is deleted or you remove the link. Share it only with people who should see the app, and do not paste it where others can read it.

Remove the link with:

cloudy-cloud open AGENT_ID 3000 --unshare

--share and --unshare take a single port, not LOCAL:REMOTE.

Two limits

  1. Start the app in the background. A turn's foreground processes end with the turn. Ask the agent to run the app like this:
    nohup npm run dev > /tmp/dev.log 2>&1 &
  2. The tunnel and link stop when the machine is deleted. A worker machine is deleted after 60 idle minutes, when the session ends, or at its deadline (6 hours by default). A coordinator lives longer (24 hours by default).

The command uses the Instabox CLI (npx --yes instabox@latest), so you must be signed in to Instabox. If it says you are not, run cloudy-cloud setup. If the agent's machine is not running, the command says so and you need to start a new agent.

For running many agents, see Coordinators and fleets.