Multiple machines

One workspace can hold more than one computer. This page covers how to connect them, and what does and does not travel between them — the second half is where people actually get caught.

The one thing to get right: a workspace is bound to a directory

icloser pair creates the workspace on the current working directory. That directory is the AI employee's entire world — everything it reads, writes, and runs commands in.

So run it inside your project directory:

If you would rather not change directory, name it with --path, and point at a gateway with --api.

⚠️ Do not run it in the folder you downloaded or unpacked the installer into. Those folders (Downloads, a temp directory, something unzipped onto the Desktop) usually hold other things too, and all of it becomes the contents of that workspace. This has actually happened: a workspace bound to the temporary folder an installer was unpacked into, with personal documents sitting in it. Newer builds refuse such a directory outright, but spelling out --path is still the easiest way to be sure.

Connecting a second computer to the same workspace

Pairing prints a join link. On the second computer, go to the directory you want it to live in and hand the link to:

Both machines now belong to the same workspace, each with its own local directory — the paths do not have to match.

Moving files: push and pull

push reports this machine's current file state; pull restores another device's state onto this machine, with --from to choose which one.

If the directory is a git repository, push sends only the difference against HEAD instead of rebuilding the whole tree every time; --full forces a complete snapshot.

Two of pull's defaults are deliberate: conflicting files are skipped, never silently overwritten, and deletions are not applied — deleting is irreversible, so you do it yourself.

What does not travel

This is the section that catches people. The following is deliberately not synced, and has to be set up again on the new machine:

• Private keys and key material — SSH private keys, .pem/.jks/.p12, signing profiles. Never synced across devices: one leak means rotating everything.
• Credentials and tokens — .env, .npmrc, .git-credentials. Not synced today either; set them up again on the new machine. push lists everything it skipped, by name, rather than quietly sending less. (Template files like .env.example do go through.)
• Very large single files — anything over 16 MiB is recorded in the manifest but its contents are not sent. The file still appears in the file list, empty. push tells you exactly which ones and how big.
• .git / .hg / .svn internals — the version control system maintains those itself; copying them across machines corrupts the repository.
• Session logs and run-time by-products — large .jsonl files, tool-result streams. Recovery needs the result, not the transcript.

When something "doesn't work" on the new machine, it is almost always the first item: a couple of credential files did not come along. The push output already named them.

Permissions do not carry across machines

Authorization is granted per machine and is never inherited from another one. A second computer joins read-only; grant it again on that machine:

This is deliberate: a decision made on one machine should not speak for another.

Two machines working in the same workspace

That works. A task belongs to whichever machine claims it first, and no task runs twice. At the file level, pull skips conflicts and reports them instead of choosing for you.

Seeing what you have

In order: every workspace on this machine (→ marks the current one), switch to one of them, who is running and which workspace they are bound to, and the current workspace's identity and directory.

icloser status prints the directory the current workspace is bound to. Glance at that line before you run push — it sends that directory, not the one you happen to be standing in.