# Cloud conversations

> Give each coding conversation its own VM, work in your own app, and keep its branch and transcript while your laptop is closed.

## Start from your project

Every new conversation starts in its own VM, with your tools, logins and project ready. Later turns reuse that
conversation's VM. Keep using T3 Code, Claude Code, Claude Desktop, Codex CLI or the Codex app.

```sh
npm i -g shardflux
shard setup
cd your-project
shard ./
```

`shard ./` opens the selected agent's own terminal UI directly. `shard ./ claude` selects Claude Code;
`shard ./ codex` selects Codex. Your project appears at `/home/user/<project>`, on the conversation's own branch.
Setup prepares dependencies and services in the background and saves the project's environment.
See the [quickstart](https://docs.shardflux.dev/quickstart.md#cloud-agents-quick-start).

New project folders work directly (CLI 0.14.2+): `shard ./` and `shard agents new` initialize Git on `main` when needed and create an empty initial commit. Existing files and staged work are preserved; repositories without commits keep their current branch. If Git identity is missing, that one commit uses `Shardflux <noreply@shardflux.dev>` without changing your Git configuration.

Close the terminal or your laptop and the cloud session keeps working. Reconnect to catch up with its output.
To continue a conversation, run `shard ./ --resume` (or `shard ./ codex --resume`): choose a saved project
conversation, then continue in the agent's own UI. `shard` opens the optional command center.

## Your machine and project template

Your **machine** carries tools, credentials, dotfiles, browser logins, git identity, Claude/Codex settings and
skills across projects. Your **template** carries this project's toolchains, dependencies, services and secrets.
New conversations start from the latest saved versions of both.

```sh
shard machine
shard machine save
shard template
shard template save
```

Install tools and configure them normally in the VM, then save the environment you want future conversations to
use. Saved files reach running conversations live. Software and platform updates apply automatically when the
agent is waiting, with no attached client or local sync and no user command running. The conversation's branch
and transcript carry it forward; its services restart from the saved setup.

[Bring credentials from your vault](https://docs.shardflux.dev/guides/credentials.md) for project secrets, browser fills and remembered logins.

Both environments are private filesystem templates and contain secrets as ordinary files. Your conversation's
working copy and service data stay its own. [Machine and template](https://docs.shardflux.dev/guides/machine-and-template.md) covers save and
rollback; [Lifecycle](https://docs.shardflux.dev/concepts/lifecycle.md#cloud-agent-environment-updates) explains updates.

## Sign in once

For Claude, follow the URL and code for one cloud sign-in per Shardflux account. Shardflux refreshes that sign-in
for your cloud sessions; your laptop's Claude login stays separate. Codex uses your copied local login.
Add `--approvals` at launch to keep interactive agent permission prompts.

## Open a session in your own app

| App | Start and continue |
| --- | --- |
| Claude Code | `shard ./ claude`; `shard ./ claude --resume` continues a saved project conversation |
| Codex CLI | `shard ./ codex`; `shard ./ codex --resume` continues a saved Codex conversation |
| T3 Code | Select **Shardflux** in an ACP-capable T3 build, then pick a Claude Code or Codex model. Each new thread gets its own VM |
| Claude Desktop | Run `shard agents open claude-desktop <workspace-key>`, restart Desktop, select **Shardflux · <project>**, and open `/home/user/<project>` |
| Codex app | Run `shard agents open codex-app <workspace-key>`, select **Shardflux · <project>** in its SSH connections, and open the project |

Desktop connections belong to the project. New conversations are routed to their own VMs; reopening a thread
uses its current binding. Your app's working indicators, permission prompts and conversation history stay familiar.
Terminal Claude sessions also open in claude.ai and the Claude mobile app through Remote Control, with `[SF] ` titles.

## Fork another approach

Say what you want in the chat:

| Ask | What the agent does |
| --- | --- |
| “Fork this and try X” | Copies the running VM's files, memory, processes and services into a child conversation with its own branch |
| “Have three agents try it” | Starts helpers in fresh VMs with individual briefs and branches |
| “Have Codex review this” | Joins Codex as a read-only reviewer of this worktree, sharing the VM’s services |
| “Move this to a bigger machine” | Resizes the VM in place, keeping its running state |
| “Bring Codex into this” | Starts another agent in this VM, with its own worktree and shared services |
| “Start over on the latest setup” | Schedules a move to a fresh VM at turn end, carrying the branch and transcript |
| “Continue in the auth conversation's VM” | Moves this conversation into that VM at turn end, with its own worktree |
| “What did payments do? Pull in its fix” | Reads its summary, transcript and diff, then fetches its branch |
| “Ship it”, “open a PR”, “keep it” or “discard it” | Confirms the choice in chat, performs it and records the result |

Helpers report their results or questions through the conversation that started them. The parent can wait while
its VM parks, and wakes for a result or question. Answer the question in that same chat.

## Where your work lives

Each conversation works on `shard/<name>`, starting from your checkout's commit. Commits are pushed to the
project's shared repository as you make them. Conversations fetch each other's branches from that repository;
your laptop fetches from the same place.

The project's shared folder also holds transcript copies, conversation summaries and artifacts such as
screenshots and test reports. Branches and transcripts are saved in the cloud before a finished conversation's
VM is removed, so the work stays available with your laptop closed.

When your laptop is online, it mirrors transcripts into `~/.config/shardflux/conversations/<project>/<conversation>/`.
After the VM is removed, the transcript moves into Claude's or Codex's normal history with the local project path.
`shard ./ --resume` opens a handed-off conversation locally in its own worktree. To continue an ended conversation
in the cloud, run `shard conversations resume <conversation-id>`: it restores the same conversation and session
in a fresh VM from your latest saved environment. The laptop can read the final saved work through a read-only
project-space reader even when every conversation VM has been removed.

## Try locally

To test the work on your laptop, run:

```sh
shard conversations list
shard conversations try <conversation-id> --path .
```

Say “Try this locally” in the chat, or use the command above. After device approval, this creates `.shard/worktrees/<name>`, syncs it both ways with the conversation's worktree and forwards its
advertised development ports to `localhost`. Your main checkout stays separate. Press Ctrl-C to stop this
terminal's sync; `shard conversations try <conversation-id> --stop` stops a helper-owned session.

## Let the agent see your app

Claude Code and Codex in the VM use its desktop with Shardflux computer use: screenshots, clicks and typing in one
batched call, next to their own tools (`coding` 13+). Ask them to start your app, open it in Chromium and check the
change. [Computer use](https://docs.shardflux.dev/guides/computer-use.md#from-the-agent-inside-the-workspace) has the details.

## Show me on my Mac

Ask the agent to run a native build, use the simulator, move a file or open a VM service at `localhost`.
The device helper asks **Allow once** or **Always for this project** on your Mac. ACP conversations use your
app's permission prompt; other routes use a macOS notification or approval dialog. Commands run as you in the
conversation's local worktree. An outside path asks for its own approval. Actions and results appear in the chat.

The menu bar starts automatically on macOS when `shard` first runs and launches at login. `shard menubar stop`
turns it off. [Device request limits](https://docs.shardflux.dev/limits.md#device-requests) and [errors](https://docs.shardflux.dev/reference/errors.md#conversations-and-device-requests)
describe bounds and retry behavior.

## Conversation release

The conversation features on these pages start with the following client versions. The package specifier
identifies the release; `+` includes later versions.

| Client | Package | Conversation features |
| --- | --- | --- |
| TypeScript SDK | `@shardflux/sdk@0.19.1` | SDK 0.19.0+ |
| Python SDK | `shardflux==0.15.1` on PyPI | Python 0.15.0+ |
| CLI | `@shardflux/cli@0.14.3` | CLI 0.14.0+ |
| MCP server | `@shardflux/mcp@0.13.0` | MCP 0.13.0+ |
| npm bundle | `shardflux@0.16.3` | bundle 0.16.0+ |

The [conversation concept](https://docs.shardflux.dev/concepts/agents.md) explains states and saved work. The [CLI](https://docs.shardflux.dev/reference/cli.md#conversations),
[TypeScript](https://docs.shardflux.dev/reference/typescript.md#conversations), [Python](https://docs.shardflux.dev/reference/python.md#conversations),
[MCP](https://docs.shardflux.dev/reference/mcp.md#conversation-tools) and [HTTP](https://docs.shardflux.dev/reference/http-api.md#conversations) references describe the interfaces.