The chopin CLI connects a machine you control to a Chopin server. Builds,
investigations and Planner work that you start in Chopin then run there, with
your own coding agent, for documents in any repository you can push to.
The machine only makes outgoing requests. Chopin never connects in, and the browser never reads your files.
chopin connect runs in the terminal you start it from. The service runs the
same connection in the background, so no terminal has to stay open. The
Machines page sets up the service, and it's the one to use on a remote machine
or a server.
| How it runs | What happens | Use it for |
|---|---|---|
chopin connect |
Runs in this terminal and stops when you close it or your SSH session ends. | Trying it out |
| The service | Runs in the background and starts again after a reboot. Closing SSH doesn't stop it. On Linux, logging out doesn't either; on macOS and Windows it runs while you're logged in. | Remote machines and servers |
chopin service install runs a copy of what chopin connect last ran.
chopin connect --install-service does both: it connects once, then installs
the service. Keep it running has the details for each
operating system.
In Chopin, open Machines and choose Add machine. It offers two ways:
- Local, a laptop or desktop you work on. You approve it in the browser.
- Cloud, a server or VM that stays connected. It uses a single-use key, so nobody opens a browser on it.
Either way you copy one command and run it in a terminal on that machine, in
any folder. The installer installs chopin, then runs chopin connect itself. If the install
fails, it stops with its own message and runs nothing.
The machine needs Linux or Windows on x86_64 with hardware virtualization: the
agent isn't installed or signed in on it, because chopin runs it in a microVM of
its own and installs it there (see Coding agents and
Sandbox). A Mac or an Arm machine can install chopin, but can't run
Chopin's work. Your server may list its own
setup agents first, each with its own steps.
Pick the system and your coding agent. On Linux the command looks like this:
curl -fsSL https://github.com/githubnext/chopin/releases/latest/download/install.sh | \
CHOPIN_URL=https://your-chopin-instance.example sh -s -- connect --install-service --agent copilotIn PowerShell on Windows:
$env:CHOPIN_URL = 'https://your-chopin-instance.example'
& ([scriptblock]::Create((irm https://github.com/githubnext/chopin/releases/latest/download/install.ps1))) connect --install-service --agent copilotIt prints a link and a code. Open the link in the browser you're signed in to, check the code and approve. The machine connects, installs the service and appears on the page.
Add machine → Cloud opens Add a cloud machine. Name the machine if you like (without a name Chopin uses its hostname), choose the agent, whether it stays connected (on by default), and whether Chopin may build and prototype on it automatically (off unless you turn it on; see Connect). Then press Generate install script. The command carries a single-use key:
curl -fsSL https://github.com/githubnext/chopin/releases/latest/download/install.sh | \
CHOPIN_URL=https://your-chopin-instance.example CHOPIN_PAIRING_KEY=chopin_k_… sh -s -- connect --install-service --agent copilotA name adds --name <name> after connect. It pairs at once, with no browser,
so it works over SSH and in scripts. The key
never goes on a command line: sh passes it in the environment of the one
installer, and in PowerShell the first line sets it in the session and
install.ps1 removes it once chopin has run. That line assigns the key to
$token first, so PSReadLine 2.0.4 and later leave it out of their history
file.
The key works once, for ten minutes, and only for the account that made it.
Chopin makes one only when you press Generate install script, and
Re-generate install script replaces it. chopin sends the key once and
never saves it. If your server needs GitHub to authorize the machine, pressing
Generate checks with GitHub first; that returns at once if you have used Chopin
before. Chopin holds that authorization for 25 minutes at most, for the browser
sign-in that asked for it only. Signing out ends it and the key it made.
To pair with a key yourself, pass it as --key or in CHOPIN_PAIRING_KEY:
chopin pair --key chopin_k_…
chopin connect --key chopin_k_… --agent copilotIf curl can't download the installer at all, it prints why and sh, given no script, runs nothing and exits 0.
A plain chopin connect you start over SSH can stop when the session ends,
even under nohup or setsid. Use the service there.
chopin installs on Linux, macOS and Windows, x64 or arm64, but only a Linux or
Windows machine on x86_64 with hardware virtualization runs Chopin's work (see
Sandbox).
On Linux or macOS:
curl -fsSL https://github.com/githubnext/chopin/releases/latest/download/install.sh | shOn Windows (x64), in PowerShell:
irm https://github.com/githubnext/chopin/releases/latest/download/install.ps1 | iexThe installer puts chopin in ~/.local/bin, or on Windows in
%LOCALAPPDATA%\chopin\bin, which it adds to your user PATH. It needs no
administrator rights and verifies the download first.
If ~/.local/bin is not on your PATH, the installer prints the line to add to
your shell profile. Then check that it works:
chopin --versionInstall your coding agent and sign in to it, as Coding agents
shows. Then run chopin connect with your server in CHOPIN_URL and the agent
in --agent. Any folder will do:
CHOPIN_URL=https://your-chopin-instance.example chopin connect --agent copilotOnce it connects, chopin connect saves the server, so you set CHOPIN_URL
only this once. Later commands use the saved server. Without CHOPIN_URL or a
saved server, chopin uses https://chopin.githubnext.com.
The first time, without a pairing key, chopin connect pairs this machine with
your Chopin account in a browser:
- The terminal prints a link and a short code.
- Open the link and sign in to Chopin.
- Check that the page shows the same code as your terminal.
- Leave Let Chopin build and prototype automatically on this machine unticked unless you want Chopin to start rebuilds and prototypes here by itself. Build and Run work without it.
- Choose Add machine. The page says Connected.
The pairing lasts until you disconnect the machine. It survives server restarts, deploys and signing out of the browser. So does a build running on the machine: the connector keeps its agent working while Chopin restarts, registers the machine again, and its heartbeat carries the build on (see Trouble connecting).
When the connection is up, you see:
✓ Connected.
Work you start in documents of any repository you can push to runs here. Ctrl-C disconnects.
It clones each repository the first time work needs it.
One connection serves every repository you can push to on GitHub. Chopin checks that you can push to a document's repository each time its work starts here.
--agenttakescopilotoratomic. For any other agent that speaks ACP over stdio, give its command after--instead, as inchopin connect -- my-agent --acp.- Set
CHOPIN_DEBUG=1to see your agent's own log. - Ctrl-C stops running work and disconnects. A second Ctrl-C exits at once.
To give your agent and Planner an environment variable, add --env, as often
as you need:
chopin connect --env SOME_FLAG=1 --agent copilotchopin saves these values in config.json, which only you can read. Keep
secrets in your agent's own login instead. You can't set PATH or a
CHOPIN_ variable this way.
Work in a repository runs from a checkout of it. By default chopin clones the
repository the first time work needs it, into
~/.local/state/chopin/connector/repos/<owner>/<repo>, and fetches it again
before each piece of work. It clones over HTTPS with the GitHub token Chopin
gives the machine. The token reaches Git only through its environment, never a
command line or the clone's own settings.
To use a checkout you already have, with its branches, dependencies and local
settings, name it with --checkout, as often as you like:
chopin connect --checkout ~/src/score --checkout ~/src/site --agent copilotEach must be a clone of a GitHub repository (its origin on github.com) with
at least one commit, and only one per repository. A path given on its own, as
in chopin connect ~/src/score, counts as one --checkout. Work in those
repositories runs from your checkouts; work in any other repository runs from a
clone. chopin status lists both.
If your server gives machines no GitHub token (AUTH_MODE=local), there is
nothing to clone with, so name a checkout of each repository you work in. Work
in a repository without one fails with
This machine has no checkout of <owner>/<repo>, followed by the command to
run.
With more than one machine connected, Chopin picks one for you by default: your default machine when it is connected and free, else the machine that last worked on the document, else the first idle one. Most people never need more than that. To pin one document to a machine, open the document's title menu and choose Machine. It shows the current choice (Default, or a machine's name) and opens the machine list in place: Default machine (with the machine it uses now), then each of your machines with its state; offline ones are greyed out. On a phone, Machine in the title's actions sheet opens the same list as a sheet. The choice is yours alone and holds for that document until you change it:
- Build plan, Build, Run and investigations you start in the document go to the machine you chose, behind any work it is already running.
- Rebuilds and prototypes Chopin starts for you follow the same choice, and still need the machine's consent to automatic work.
- Where Chopin runs Planners on machines, the document's Planner runs there too, and on Default machine it runs on the creator's; see Run a Planner on this machine.
- The list also shows machines teammates share, sorted with your own, newest paired first, under Local or Cloud, when they serve the document's repository and their owner can push to it. Anyone who can edit the document may choose one, and its Planner, your builds and your runs then run there, as its owner; see Share a machine with teammates.
- If the machine you chose is offline, Build plan is greyed out, as offline
machines are in the list, and starts nothing. It changes within a few seconds
of the machine going offline or coming back, as does the Machines count in
the sidebar, without a reload; a screen reader hears build-box is offline
(your machine's name). Other work fails with those words rather than moving
to another machine. Start
chopin connecton it, or choose another one. - If Chopin can't read your choice (its database is briefly unavailable), work fails with Can't read your machine choice right now. Try again. It never falls back to another machine; once the choice can be read, it applies again.
- Choosing Default machine goes back to Chopin's pick.
Disconnecting a machine clears every choice of it, and everyone's default of it.
Choose your default machine from Machines in the sidebar: it opens a menu listing Any connected and each machine you can use under Local or Cloud with its state, yours and the ones teammates share sorted together, newest paired first, then Add machine and Manage machines for the full page. Beside the machines it shows how many are connected out of all of them, such as 2/2. The default is the machine marked as your favorite on the Machines page too (its star, or Set as favorite in its menu). Only one machine is your default, yours or a teammate's. Chopin uses it first whenever it is connected and free, and otherwise picks as before; a machine you chose for a document never moves. Your default is yours alone and applies to every document left on Default machine. A teammate's machine is your default only while its owner shares it and can push to a repository you can: when they stop sharing it or disconnect it, it stops being your default.
The Machines page offers these agents. Connect with is what follows
chopin connect, and Runs is the command and variables it starts:
| Agent | In its microVMs | Connect with | Runs | Tested with Chopin |
|---|---|---|---|---|
| GitHub Copilot CLI | @github/copilot@1.0.114 |
--agent copilot |
copilot --acp --allow-all |
Yes |
| Atomic | @bastani/atomic@0.10.3, @bastani/atomic-acp@0.0.18 |
--agent atomic |
ATOMIC_ACP_HEADLESS=1 atomic-acp |
Yes |
You don't install the agent on this machine, and it doesn't need Node.js:
chopin runs every agent in a microVM of its own, from an image it builds once
with the agent installed at the version this chopin pins (see Sandbox).
The agent runs on the AI accounts of the person a job is for, which they connect in
Chopin, so it needs no sign-in here either. The service can't answer a permission
prompt, so Copilot CLI runs with --allow-all to approve its tools without asking.
Atomic doesn't ask, and ATOMIC_ACP_HEADLESS=1 ends its questions at once instead
of waiting for an answer.
Arguments after -- go to the agent. For example,
chopin connect --agent atomic -- --model openai/gpt-5.5 runs
atomic-acp -- --model openai/gpt-5.5, which passes them on to Atomic. An
--env you give wins over the agent's own variable of the same name.
For any other agent that speaks ACP over stdio, give its command after --
instead of --agent, with its approval flag if it has one, and how to install it
in its microVMs with --install (repeat it for several commands). The commands run
in the image's build, with Node.js and npm, whose global installs go into the image:
chopin connect --install 'npm install -g my-agent' -- my-agent --acpA Planner command is installed the same way with --planner-install. An agent
chopin has no recipe for is refused before anything is paired, naming the option.
The build reaches the network only through the proxy, with no credentials
of yours, and runs whatever install scripts the packages have. To install something
that needs a sign-in, such as a package from a private registry, fetch it on this
machine yourself and name its folder with --install-from. The build gets a copy
of that folder, read-only, at /install-from; no agent's microVM gets it:
npm pack @my-org/my-agent@1.2.3 --pack-destination ~/agent-packages
chopin connect --install-from ~/agent-packages \
--install 'npm install -g /install-from/my-org-my-agent-1.2.3.tgz' -- my-agent --acpWhat the folder holds is part of the image, so a changed file builds the image
again. Keep the folder: the service reads it each time it starts. It may hold only
files and folders, not links. npm installs into /opt/chopin/agent, so a package
installed with npm install -g is at /opt/chopin/agent/lib/node_modules/<name>
in the agent's microVM, and its programs are on the agent's PATH.
chopin service install runs your connection in the background, so it starts
again after a reboot and needs no open terminal. Anything that should outlive
your login session belongs in the service. It copies what chopin connect
last ran, server included, and runs that copy. The settings store the full path
of the agent chopin connect found, so the service runs that same agent
whatever your PATH is when you install it.
The quickest way is one command. It connects, and once it sees
✓ Connected. it disconnects and installs the service:
chopin connect --install-service --agent copilotYou can also do it in two steps:
-
Run
chopin connectonce, as above, and press Ctrl-C after✓ Connected.A connect that stops before then saves nothing. -
Install the service:
chopin service install
Before installing, chopin starts your agent once the way the service will,
with the service's PATH and your --env values, and waits up to 10 seconds
for it to answer. If it doesn't, nothing is installed, and the message shows
the first line your agent printed. For an agent that can't start without a
terminal, pass --skip-check.
The service can't answer permission prompts. The built-in agents already approve their own tools; give any other agent its approval flag.
A later chopin connect doesn't change what the service runs. To change it,
run chopin connect with the new arguments, then install again:
chopin connect --checkout ~/src/other-project --agent copilot
chopin service installWhile the service is running, chopin connect doesn't connect a second time.
It saves your settings and prints:
The chopin service is running on this machine. Saved your settings; run chopin service install to use them.
Each operating system has its own catch:
- Linux. A systemd user service. Install turns on linger so it keeps
running after you log out. If that needs an administrator, install prints
the
sudo loginctl enable-lingercommand for them. Never runchopinitself withsudo. Whenloginctlcan't answer, install and status read systemd-logind's own record,/var/lib/systemd/linger/<user>, and say so. - macOS. A LaunchAgent, which runs only while you are logged in.
- Windows. A Task Scheduler task, which runs only while you are logged on.
Machines in Chopin lists your machines with what each connector last said
about itself: its hostname, its chopin release and system, the coding agent it
runs, and whether it is connected (a green dot) or when it was last seen.
Search finds a machine by any of these. Edit machine name… in a machine's
menu renames it in Chopin, and chopin status shows that name. Only you see
your machines, except one you share with teammates: they see it in the same
table, sorted with their own, read-only: its name, its owner, its chopin release and
whether it is online, with its Shared switch on and disabled. A teammate
who can push to a repository you both can sees it there without having opened a
document in it; see
Share a machine with teammates.
On the machine:
chopin statusYou see something like this:
chopin 0.0.11 (connector protocol 5)
Server: https://your-chopin-instance.example (saved by chopin connect)
Machine: paired as build-box (octocat); Chopin accepts it
Connector: running (pid 4242, chopin 0.0.11, the service)
Service: running (systemd, pid 4242)
definition: /home/me/.config/systemd/user/chopin.service
runs --agent copilot (/home/me/.local/bin/copilot --acp --allow-all) with checkouts /home/me/src/score, on https://your-chopin-instance.example
Checkouts: octo-org/score at /home/me/src/score
Clones: octo-org/site at /home/me/.local/state/chopin/connector/repos/octo-org/site
Runs: 4 finished runs kept (1.2 GB), 1 running
Planners: /home/me/.local/state/chopin/connector/planners/octo-org/score/5f0c…e21 (octo-org/score, document 5f0c…e21)
Log: /home/me/.local/state/chopin/connector/chopin.log
Base dir: /home/me/.local/state/chopin/connector
If you have connected something else since you installed the service, status
shows that too, with a reminder to run chopin service install.
If the agent or a Planner keeps failing to start, status shows the latest
failure under the connector, with the first line it printed. That line, and
everything a Planner prints to chopin's output on stdout or stderr, has
anything that looks like a token, your --env values of 8 characters or more
and the Planner's credential replaced with [redacted]. A line too long to
mask is left out, with a note in its place:
Connector: running (pid 4242, chopin 0.0.11, the service)
Planner for https://your-chopin-instance.example/octo-org/score/plan: failing (exit 127: /usr/bin/env: 'node': No such file or directory), retrying in 22s
A Planner that Chopin refused for good, such as one for a deleted document,
shows stopped: and the reason instead of failing.
The people in the document can read why too, not only whoever runs the
machine. After each launch of a Planner Chopin asked this machine to run that
exits before staying up, the connector tells Chopin how many launches in a row
have, how the last one ended and the last line it printed to stderr that says
why (a closing "Exiting with code 1" notice does not count), with tokens and
--env values masked, your home directory shown as ~ and the line cut at 300
characters. From the second launch in a row, the document's machine button turns
its dot to a warning and its menu says Can't connect to studio with the steps
to fix it (see Can't connect to a machine),
while the connector keeps retrying. Once the Planner attaches, or a launch stays up, it
goes. A Chopin from before this does not know the report; the connector asks it
once and carries on.
A chopin older than 0.0.23 cannot make the report, and a Planner that never attaches
without exiting makes none, so Chopin says what it saw itself. Each launch asks Chopin for a
credential, so from the third launch in a row the machine's Can't connect reads
It started and stopped again before it connected, with the release the machine runs and
chopin update where that release is older than 0.0.23. Two minutes after a machine was asked, with
no Planner attached, it reads It hasn't answered yet or It started but hasn't connected yet
and Waiting since 7:26 PM, whatever release it runs. Run chopin update on that machine and
restart the service (chopin service restart): its next failure then comes with the reason
the Planner printed.
A connector started with --planner-command says it can run Planners, and
lists each Planner it runs because Chopin asked this machine for it
beside the --planner ones (canRunPlanners and chosenPlanners in
--json):
Connector: running (pid 4242, chopin 0.0.11)
Can run Planners for documents that choose this machine
Planner for https://your-chopin-instance.example/octo-org/score/plan (chosen in Chopin)
chopin status asks Chopin whether it still accepts this machine. It never
pairs, connects or changes anything.
If your Chopin server runs HARNESS=remote (and not AUTH_MODE=local), this
machine can run a document's Planner. Pass the document's URL with --planner
and your Planner backend's command with --planner-command:
chopin connect --planner https://your-chopin-instance.example/octo-org/score/plan \
--planner-command "my-planner --flag" --agent copilot--planner can repeat. chopin runs the command for each document in the
checkout of the document's repository, yours or a clone (see
Your checkouts and clones), and restarts it when it
exits. The command connects to Chopin itself,
over the agent connection. See
Planner backend commands for what
it must do.
With --planner-command alone, the machine says it can run Planners without
naming any document:
chopin connect --planner-command "my-planner --flag" --agent copilotChoose this machine for a document under Machine in its title menu, and
Chopin asks it to start that document's Planner, unless another account holds it. The backend
gets its credential as with --planner.
A document left on Default machine gets its Planner too, on a machine of
the person who created it, picked as for builds: their default machine when it
is connected and can run Planners, else the machine that last worked on the
document, else any of theirs that can. Chopin asks for it while someone has the
document open, and from the moment its creator makes it with New document, before
their page has loaded it, and stops it once nobody has used the document for 30 minutes.
A Planner that is replying, or waiting on a question, counts as use, so its work and its
questions are never cut short
however long nobody views the document.
A Planner stays on its machine while that machine is connected, even when
another comes online; it moves when the machine disconnects or the creator
changes the document's machine or their default. Until it attaches, the
machine button's dot is three petrol dots that brighten in turn and its name says Connecting to
studio (the machine's name), and an @chopin message sent meanwhile waits for
it. Once it has attached the button says nothing more about it.
Chopin asked a machine to run a document's Planner, and the Planner's backend
exited before it stayed up, more than once in a row. Nothing about it is drawn in
Chat. The machine button, left of Build plan, has a warning dot, and its menu
opens onto Can't connect to studio: one sentence of why, numbered steps (such
as chopin status on the machine, in a block with a Copy button) and
Learn more, which links here. Show
details unfolds the last line the backend wrote to stderr that says why, exactly
as reported, and when it was last tried. chopin's avatar carries the same warning
dot. A person who has no machine button, such as a teammate with no machine of
their own, sees it there, and when they ask chopin something it can't take, chopin
says so in a row only they see, with How to fix unfolding the same steps under
Can't connect to @mona's machine, since only the owner's login is ever named,
never the machine. A screen reader hears Can't connect to studio once, as it
appears, from a live region of the page.
Chopin keeps retrying, and the connector backs off between launches, so nothing needs pressing once the cause is fixed: the next launch attaches, the warning goes without a word, and the button's dot returns to the machine's own.
To fix it, start from the reason: it is the backend's own last line that says why,
with tokens and your home directory masked. On the machine itself, chopin status
shows the same failure under the connector with how the backend ended, such as
exit 127: /usr/bin/env: 'node': No such file or directory for a program that is
not on the connector's PATH, and the Log line it prints names the file with
what the backend wrote. Change what the reason names on that machine (an
environment variable passed with --env, a missing program, a checkout), or
choose another machine for the document from the machine button.
Sharing a machine lets teammates run their work on it. It is off unless its owner turns it on: with Run teammates' work as they add the machine (Let teammates run their work on this machine on the pairing card), or later with the machine's Shared switch on the Machines page (Share with teammates in its view on a phone). Turning it on is the owner's consent to three things for a document whose teammate chose the machine, in repositories the owner can push to:
- its Planner runs there, as the owner, with the owner's GitHub authorization; on Default machine it also does so for a document whose creator has no machine of their own that can run Planners;
- Build plan, Build, Retry, Run and investigations the teammate starts run there, behind any work the machine is already running. The agent runs on the owner's machine with the owner's GitHub account, so its pull requests are opened by the owner, not the teammate. Chopin records the teammate as the person who asked, shows their name on the build, and tells the agent to end each pull request body with a note naming who requested it;
- nothing automatic: rebuilds and prototypes Chopin starts by itself still run only on the machine of the person whose living document they are, and only where that machine's owner ticked automatic work. They never run on a teammate's machine, chosen or not.
A build there is claimed and reported only by the machine it was queued on. It is queued only while the machine is shared, its owner can push to the repository, and the teammate has chosen it; it is not taken once any of those stops being true, and ends within a few seconds saying so. A build already running keeps going until it finishes, like a Planner mid-reply.
- A teammate sees a shared machine, read-only, in the one table on
Machines, sorted with their own, newest paired first, under Local or
Cloud: its name, its owner, when it was paired (the order of the list, not
shown), whether it is online and its chopin release. It serves every repository its
owner can push to, so a machine with no checkouts counts too. A machine that
is not shared, or whose owner can't push to a repository, is never listed to
anyone who works there; nobody but its owner can rename it, change its sharing
or disconnect it. A teammate may star it, as their default. For a machine
that serves every repository, the page intersects two lists of what can be pushed to among GitHub App installations:
the teammate's own, held a minute, and its owner's, listed with the machine's
own token and held 10 minutes for everyone who looks (a minute after a failure).
Neither list is cut short, and nothing is asked of GitHub for each repository,
so the page's refresh every few seconds, and any number of teammates, cost the
owner's GitHub rate limit a few listings every 10 minutes. A teammate need not
have opened a document in a repository first. For the repositories a machine
has checkouts of, each is asked on its own a few at a time and held as the
owner's check is (below): the teammate's own check, for a repository their
installations don't list, is made with their own login and kept 10 minutes for a
pass and a minute for a refusal. It is listed wherever Chopin has machines,
with or without Planners on machines; under
AUTH_MODE=local, where machines hold no GitHub authorization of their own, only while its owner is signed in. - A document's Machine list offers it the same way, among the Local and Cloud machines, to anyone who can edit the document and push to its repository, and online or offline like your own. Choosing it sends your builds and runs there, and that document's Planner too where the rules below allow. Chopin checks with the machine's own token that its owner can push to the repository before it lists or asks it, and again every 10 minutes. If it is offline, Build plan is greyed out and says so, as for your own; if its owner stopped sharing it or can't push any more, a build or run fails saying that, and never moves to another machine.
- The document's creator's choice still decides where its Planner runs. Another
editor's choice of a machine places it only while the creator has chosen no
machine, and only on a machine that can run it for them now: online, started
with
--planner-command, and (for a teammate's) its owner able to push. Then it takes the Planner from Default machine's machine: a Planner attached there stops, one that was only asked is withdrawn, and only the chosen machine is asked. The choice is stored, so it still holds after Chopin restarts, and Default machine is not asked for the document while a stored choice places it. A choice of a machine that can't run the Planner now (offline, started without a Planner command, or its owner can no longer push) is stored and stops nothing: the Planner keeps running where it is, a reply under way included. The chosen machine takes it once it can run it: at once when no Planner is attached on Default machine, otherwise once that one has ended. A machine coming online never interrupts an attached Planner. Choosing another machine replaces your earlier choice, so a Planner on the machine you chose before stops. When the creator chooses their own machine, or Default machine, the Planner on an editor's machine stops and the editor's choice that placed it goes, even if that machine had not been asked yet. An editor's choice made while the creator's own stood is only stored, for their own builds and runs, and counts again once the creator chooses no machine. Builds and runs follow each person's own choice, whoever created the document. A person whose choice does not place it is told so in the machine menu, above the machines: The document's creator chose where its replies come from, so your choice runs your builds and runs. What Chat says of the Planner keeps naming the machine it is on. - A document left on Default machine whose creator has no connected machine that can run Planners uses a shared one too. Builds, runs and investigations never go to a teammate's machine unless the person chose it for the document or made it their default.
- A teammate's machine that is the creator's default is where Default machine runs their Planner first, and where Automatic sends their builds, runs and investigations first, while it is online, serves the repository and its owner can push to it; where it doesn't, they go where they would without it. A choice for the document comes before it. A rebuild they press follows their default as it is now, so a shared machine they made their default after the first build runs it, ahead of the machine that build ran on. Rebuilds and prototypes Chopin starts by itself stay on their builder's own machines.
- With several shared machines, each owner's default goes first.
- Once the creator connects a machine of their own, the Planner moves there, unless it is already attached on the shared machine; then it stays until it stops.
- Turning sharing off takes the machine off teammates' lists and clears their
choices of it and their default of it, and takes no new teammate work. A build still waiting on it
ends. A document whose Planner the machine was not running, had not been asked
to run and was not about to run, and that nobody is using, only loses the
choice: nothing starts for it on the creator's machine. A teammate's Planner
that is idle stops at once; one that is replying or has a question open keeps
going until that work finishes, then stops within 15 seconds. A build or run
already going finishes. Meanwhile the machine's row on Machines says
Finishing 1 teammate document. Each stop prints why:
<owner> stopped sharing <machine> with teammates.
Choosing another machine stops it and prints
Stopped the Planner for <document>: the document chose another machine. So do
moving it, disconnecting or revoking the machine, leaving the document unused,
or losing push access to the repository.
Chopin then voids the credentials it gave the machine for that document.
One machine runs the Planners of documents in as many repositories as you choose it for.
In the Machine list, a machine started without --planner-command is
greyed out.
chopin connect keeps its files in its base dir,
~/.local/state/chopin/connector, never in your checkouts.
Where chopin keeps its files
lists them all.
| Path | Holds | Removed |
|---|---|---|
runs/<run id>.json, runs/<run id>.agent/ |
A job's record, and its agent's state where it ran on Chopin's AI accounts | Once 15 newer runs have finished |
planners/<owner>/<repo>/<document id>.disk |
A Planner's disk, with its own clone of the repository | When Chopin says its document is archived or gone or its Planner was reset, after 30 days unused, or when the machine is unpaired |
repos/<owner>/<repo> |
A clone of a repository you named no checkout of | Never |
images/ |
The agents' images, built once each | When the connector that holds the base dir starts and no recipe names one any more |
nvx/ |
The NVX release this chopin pins, and its microVMs' records |
An NVX release chopin no longer pins |
git/<process>/ |
A copy of the settings of your git configuration that chopin's own git commands use (where to fetch from, proxies, line endings) |
As that chopin exits, or by the next chopin connect once it is gone |
agent-store/ |
This machine's database login for agent sessions, and the adapter | Its password with chopin unpair |
A run leaves no worktree: its agent worked in its microVM, and pushed what it kept.
Nor does it leave anything in your temporary directory: NVX's own folder for each
microVM (nvx-sandbox-run-*) goes when the microVM ends, even when it was stopped by
force, and chopin connect removes any a chopin that was killed left, once no
microVM uses it.
--keep-runs <n> keeps n finished runs instead of 15, and --keep-runs 0
keeps them all. chopin never removes a run that is going or waiting to start.
chopin connect runs every agent and Planner command that does work in a microVM
of its own: an NVX guest, a small Linux virtual
machine under your system's own hypervisor (KVM on Linux, the Windows Hypervisor
Platform on Windows), with its own kernel. A mistaken or hostile instruction in a
document reaches only what that microVM was given. Nothing else of your machine is
in it: not your home, your other checkouts, your credentials or your agents'
logins. The design is Agents in NVX microVMs.
There is no other way an agent runs. A machine that can't run microVMs, a Mac, an
Arm machine, or one whose user can't use the hypervisor, can't be paired or
connected, and chopin says why and what fixes it:
This machine can't run Chopin's work: Chopin runs each agent in its own microVM,
which needs Linux or Windows on x86_64 with hardware virtualization. Your user can't
read and write /dev/kvm.
Fix: sudo usermod -aG kvm $USER, then log out and in again (for the chopin service,
restart the machine or run: sudo systemctl restart user@$(id -u))
chopin status, the line chopin connect prints once connected, and the
machine's Sandbox row on the Machines page say where its agents run:
Agents: Each agent in its own microVM (NVX on KVM)
Agents: Can't run here: <why>
Fix: <the one command>
A machine paired before it could run microVMs tells Chopin why it can't as it stops, and the Machines page shows it while the machine is away.
The first chopin connect downloads NVX (about 275 MB on Linux, 150 MB on
Windows, checked against the SHA-256 this chopin pins) and builds the agent's
image, once, which takes a minute or two and says so. A microVM then starts in
under a second.
| In its microVM | |
|---|---|
| Works in | A repository of its own in the microVM, cloned as it starts: a run's in the microVM's memory, a Planner's on a disk of its own that lasts between its starts (see Repositories in its microVM). It pushes what it keeps to GitHub. |
| Writes | Its own repository and the rest of the microVM's own file system, its agents' state where it runs on Chopin's AI accounts, and what you add with --sandbox-write. Nothing of your checkouts or their git directories, nothing else of your machine. |
| Reads | The git directory its repository is cloned from, read-only; for a Planner, your checkout too, uncommitted files included, read-only; its own token folder. Nothing else of your machine: not your home, ~/.ssh, your other checkouts, the connector's state directory or another run's files. |
| Network | Only through a proxy on your machine that allows the hosts below and refuses the rest. A direct connection, DNS, IPv6 and your machine's other local services are closed to it. |
| Environment | What the run or Planner is given and nothing of the connector's own: its tokens, --env values, the proxy's variables, and an allow-list on Chopin's AI accounts (see below). It reaches the microVM in a 0600 file, never on any process's command line. |
| Programs | Its image's: Node.js 24, git, the agent at the version this chopin pins, and the guest's Ubuntu. Nothing you install on your machine changes them. |
Hosts an agent may reach (the full list is HOST_GROUPS in
apps/connector/src/sandbox-policy.ts):
- your Chopin server's origin, with its port;
- GitHub:
github.com,api.github.com,codeload.github.com, Git LFS, and the hosts GitHub serves raw files and release downloads from (objects.githubusercontent.com,raw.githubusercontent.com,release-assets.githubusercontent.com,github-releases.githubusercontent.com); - the model providers:
api.anthropic.com,api.openai.com,chatgpt.com,auth.openai.com,generativelanguage.googleapis.com,oauth2.googleapis.com,*.githubcopilot.com,copilot-proxy.githubusercontent.com,openrouter.aiand*.openai.azure.com; - certificate revocation checks (DigiCert, Sectigo, GlobalSign, SSL.com, IdenTrust, Microsoft and Let's Encrypt OCSP and CRL hosts), which Java, .NET and package managers make while they download;
- the package registries and toolchain downloads of every common language, since a run builds and tests whatever language it verifies: JavaScript and TypeScript (npm, Yarn, pnpm, JSR, Node, Bun, Deno), Python (PyPI, uv, conda), Rust (crates.io, rustup, docs.rs), Go (the module proxy and checksum database, Go downloads), the JVM (Maven Central, Google's Maven, Gradle, Apache downloads, Adoptium, Azul, JetBrains, sbt, Clojars), .NET (the SDK and NuGet), Ruby, PHP (Packagist, Composer), Perl (CPAN), Lua (LuaRocks), Haskell (Hackage, GHCup), OCaml (opam), Elixir and Erlang (Hex), Swift (swift.org, CocoaPods), Dart (pub.dev), Julia, R (CRAN), Zig, C and C++ (Conan), Bazel and Nix;
- the hosts you add.
Every built-in host is a fixed public service. None is general-purpose storage
that a stranger could write to and read back, such as
storage.googleapis.com, a *.blob.core.windows.net account, Amazon S3, gists
or a paste site, since those are where an injected instruction would send what
an agent read. A test keeps it that way.
The registries and GitHub still accept a publish or a push from whoever holds
a token, so the list narrows where data can go but doesn't close every path.
If a project needs one of those storage hosts, as Flutter's SDK does
(storage.googleapis.com), add it yourself. The groups follow the lists that
GitHub's agentic workflows, Claude Code on the web and Codex maintain.
The first time the proxy refuses a host, the terminal says so and which flag
allows it. Add hosts and writable directories as you connect; they are saved
with the rest of the settings, so run chopin service install again to give
them to the service:
chopin connect --agent atomic \
--sandbox-host registry.corp.example \
--sandbox-host '*.corp.example:8443' \
--sandbox-write ~/.npmA host is host, *.host (subdomains, not the bare domain) or host:port;
without a port an entry allows 80 and 443. The proxy sees names and ports, never
what a tunnel carries. It refuses a built-in name (GitHub, a model provider, a
registry) that resolves to your own machine or its networks, because a public
service has no business there. Your Chopin server's origin and the hosts you add
are your choice, and may be on a private network, as a self-hosted server or a
corporate registry is.
| Option | What it does |
|---|---|
--sandbox-host <host> |
Allows an agent to reach one more host. Repeat it. |
--sandbox-write <dir> |
Shares one more directory with every agent, writable, such as a package cache or a local remote, but never a checkout. Repeat it. |
--sandbox-hide <path> |
Hides one file or folder inside what agents are given, even inside a --sandbox-write directory, such as a tool's own sign-in. Repeat it. |
--install <command> |
How to install an agent chopin has no recipe for in its microVMs' image. Repeat it for several commands. |
--planner-install <command> |
The same for the Planner command. |
--install-from <dir> |
A folder those commands read, copied read-only to /install-from in the image's build and in no agent's microVM. |
--require-sandbox and --no-sandbox are gone: there is nothing to require and
nothing to turn off. Settings an earlier chopin connect saved with them work, without
them.
The agent of a build, investigation or prototype runs on the AI accounts that the person it runs for connected in Chopin (see AI credentials), never on yours. The connector asks Chopin for the run's launch with the run's credential before the agent starts, and the agent runs on those accounts with nothing of yours:
- Stand-ins, not keys. The agent's environment sets each granted provider's
key variable (
OPENAI_API_KEY,ANTHROPIC_API_KEY,COPILOT_GITHUB_TOKEN, and for a ChatGPT or Claude sign-inCHATGPT_ACCESS_TOKENorCLAUDE_CODE_OAUTH_TOKEN) to a random stand-in that works only through Chopin, andOPENAI_BASE_URLandANTHROPIC_BASE_URLto a relay in the connector on127.0.0.1, which the microVM reaches through the proxy. Without an OpenAI key, a ChatGPT sign-in also takesOPENAI_API_KEYandOPENAI_BASE_URL; without an Anthropic key, a Claude sign-in takesANTHROPIC_BASE_URL. Atomic finds a sign-in as itsopenaioranthropicprovider, ahead of a key, which keepsopenai-apioranthropic-api. The relay adds the launch's own credential (x-chopin-launch) to each request and forwards it to that provider's base URL on Chopin and nowhere else; the credential stays in the connector's memory and is never in the agent's environment, files or command line. A stand-in copied out of the microVM reaches nothing. - Each provider's base URL with its key, for any agent.
CHOPIN_AI_PROVIDERSholds, as JSON, one entry per granted provider, Copilot included, with what an agent needs to reach it and nothing else (an example follows the list):provider,baseUrl,apiKey,keyVariableand, for Copilot,headers. SendapiKeyas the provider takes its key (Authorization: Bearer, orx-api-keyfor Anthropic) tobaseUrlwith the provider's own paths after it (Copilot's/modelsand/chat/completions, OpenAI's and ChatGPT's/v1/…, and Anthropic's and Claude's/v1/…; a Claude stand-in goes asAuthorization: Bearer, and Chopin adds the headers and the leading system block a Claude subscription needs, as Atomic sends them), withheadersadded. EachbaseUrlis on the relay; the launch's own credential is in none of it. An agent that reads no provider's variables, any agent that is not Atomic, reaches every granted provider with its pair alone. - Nothing of your environment. The agent's environment is built from an
allow-list, not by taking known secrets out, and its microVM has its own
PATH,HOMEand tools, so a provider key or another service's token in the connector's environment never reaches it. Your--envvalues reach it, but for GitHub credentials and your agents' own model keys and directories. - A state directory of its own. The agent keeps its state in a folder of the
run's,
<base dir>/runs/<run>.agent, shared with its microVM:ATOMIC_CODING_AGENT_DIR,ATOMIC_ACP_DIR(atomic-acp's session map),COPILOT_HOME,CLAUDE_CONFIG_DIRandCODEX_HOMEpoint there. None of your agents' configuration, logins or sessions (~/.atomic,~/.copilot,~/.claudeand the rest, wherever your environment moves them) is in its microVM, so nothing of them can be read. - Atomic finds a generated
models.jsonthere that sends each granted provider (andopenai-apiandanthropic-api) to its base URL on the relay, withapiKeynaming the provider's key variable, and reads the model catalog through Chopin (ATOMIC_MODEL_CATALOG_URL). - When it ends. The connector ends the launch when the run ends; Chopin also ends it when the run ends there, if that end never arrives. When Chopin ends it first (your machine revoked, the document archived, its deadline), the relay hears it from Chopin with the launch's own credential once the proxy refuses a request, and the connector stops the run, once.
CHOPIN_AI_PROVIDERS, for a run granted Copilot and Anthropic:
[
{
"provider": "github-copilot",
"baseUrl": "http://127.0.0.1:43123/…/github-copilot",
"apiKey": "chopin_ai_…",
"keyVariable": "COPILOT_GITHUB_TOKEN",
"headers": { "Copilot-Integration-Id": "vscode-chat" }
},
{
"provider": "anthropic",
"baseUrl": "http://127.0.0.1:43123/…/anthropic",
"apiKey": "chopin_ai_…",
"keyVariable": "ANTHROPIC_API_KEY"
}
]A run whose person has no AI account Chopin can use never starts its agent: no
Copilot seat and no API key, Chopin says so (no-ai-account), and the run ends in its
words, "chopin needs an AI account to run this, so it didn't start. Add one, then start
it again.", or, where GitHub couldn't be asked about their Copilot access, that the
check couldn't finish. Your own sign-ins and keys are never used in its place, on your
machine or a shared one. A run against a Chopin from before AI launches (which answers
404) starts its agent with no models of yours either: none of your setup is in its
microVM, so it has only what --env gives it.
A Planner backend gets its sessions' grants over the
agent connection. When Chopin says its
Planners' sessions run on people's AI accounts ("ai": "chopin" in
/api/connector/version, which the connector reads as it starts, and in each Planner
credential's answer), the connector starts the backend, cold or as a spare, the same
way: an allow-listed environment, its agents' state in a folder of its own beside its
disk, and CHOPIN_AI=chopin, so its models come only from the grants it is handed. A spare started otherwise is replaced, never handed such a document.
Against a Chopin that says nothing of it, a backend starts as before. Give a backend
what it needs in its own --planner-command or in --env, not in the connector's
environment, which it then gets only an allow-list of.
Where the Chopin you connect to gives machines a database for their agents' Atomic
sessions, pairing and chopin connect set it up with nothing more to do: the
connector asks Chopin for this machine's own login, saves it in agent-store/ in its
base dir (the password apart, only you can read it), installs a 0.10 release of the
@bastani/atomic-storage-postgres adapter there with npm (once, and again only to
replace an earlier release; a failed install leaves the one there as it was), and says so:
Agents here keep their sessions in this machine's own database at db.example.com:5432.
Each agent that runs on Chopin's AI accounts, and each such Planner, then finds in its
own Atomic directory (in its agents' state, <run>.agent/atomic) a copy of the adapter, its
storage-password (mode 0600) and a settings.json whose storage selects the
database by a URL without the password. A Planner started once the machine has no
database login (Chopin stopped giving one, or this connect couldn't set it up) finds
that storage and its password taken out again, the rest of its settings kept, and
keeps its sessions in its agents' state. Your own ~/.atomic is never touched. The
proxy allows the database's host and port, which Atomic's adapter in the microVM
reaches through HTTPS_PROXY.
If Chopin can't make the login, or the adapter can't be installed, the connector says
why and connects anyway; the Machines page shows it too, until a connect reports it
set up, even while the machine is away. chopin pair on its own, which connects
nothing, tells Chopin at once. Agents keep their sessions
on the machine until a later connect sets it up. When Chopin can't be reached, the
saved login is used. chopin unpair removes the saved password, and Chopin turns the
login off. The proxy allows the database's host and port whether the URL
names a host, an IPv4 address or an IPv6 address in brackets ([2001:db8::1]:5432).
An agent never works in a folder of your machine. As its microVM starts, it clones the repository into its own file system, and works and commits there:
- A run (Build, Run, Retry, an investigation or a prototype) clones with
git clone --sharedfrom the git directory of your checkout of the repository (orchopin's own clone of it inrepos/), which its microVM reads and never writes, checks out the run's commit, and makes its branch.--sharedreads your objects where they are and copies none, so a large repository clones in seconds. The clone is in the microVM's memory and ends with it: what the agent keeps, it pushes. - A Planner keeps a disk of its own beside its tokens,
planners/<owner>/<repo>/<document id>.disk: a sparse 32 GiB image that takes only what it holds. Its first start clones your checkout's repository there, at your checkout'sHEAD, copying the objects it needs so the clone outlives your owngit gc. Every later start finds it as it was left. It reads your checkout too, read-only and uncommitted files included (CHOPIN_CHECKOUT); its own clone isCHOPIN_WORKTREE.
What this changes for you:
- No worktree folder is left after a run.
runs/keeps each run's record and its agent's state; its work is on GitHub. - A run's or Planner's branches appear only once pushed. They are never in your
own repository, so
git branchin your checkout shows them only after agit fetch. - Nothing an agent writes reaches your checkout or its git directory, and
chopinruns no git in a tree an agent wrote. - A Planner's unpushed commits live on its disk. The disk goes when Chopin says its
document is archived or gone (asked as
chopin connectconnects and every hour), when someone resets the document's Planner in Chopin (as it next starts here, or at the next hourly check), when no Planner has run on it for 30 days, or when this machine is unpaired or revoked, never while a microVM runs on it. Its unpushed commits go with it, and the connector says so. - Your checkout over the share is slow to walk. Reading a whole large checkout from a microVM is much slower than on your machine, so a Planner reads it for what is uncommitted and does its own work in its clone.
A prototype's agent still can't push anything, and in a run the agent pushes with the token Chopin issued for that one repository (see Which GitHub account pushes).
Linux on x86_64, with read and write access to /dev/kvm for your user (or
/dev/mshv under the Microsoft Hypervisor). Most distributions give it to the kvm
group: sudo usermod -aG kvm $USER, then log out and in again. A systemd user service
gets the new group only once user@$(id -u).service restarts or the machine reboots.
On a cloud VM choose a size with nested virtualization. Nothing else needs
installing: chopin downloads the NVX release it pins from NVX's own GitHub
release as it first connects, and builds the agent's image with Node.js and git.
Windows on x86_64, with the Windows Hypervisor Platform turned on
(Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform, then
restart). Windows hosts are not yet ready for work: what is left is in
Agents in NVX microVMs.
macOS and Arm machines can't run Chopin's work: NVX boots x86_64 guests
under KVM, MSHV or WHP, none of which they have. chopin installs on them, and
says so when it would pair or connect.
- The first connect downloads NVX and builds the agent's image, which can take a
few minutes; later ones start at once. A new
chopinthat pins another NVX or agent version builds the image again. - Caches. A microVM starts with none of your package caches. Add
--sandbox-write ~/.npm(or another tool's cache) to share one, writable, with every agent. - Git over SSH can't leave the microVM; Chopin's own git commands and the agent's use https with the token Chopin issued.
- A local
file://remote or another folder of yours needs--sandbox-write. - Agents that ignore the proxy can't reach the network at all. Node's
fetchis set to use it, and git, npm and curl honor it. - Memory. Each microVM takes up to 2 GiB of guest memory, about 200–330 MB of your machine's while idle.
- A busy machine. Under heavy load OpenVMM sometimes can't start a microVM (its log
says
driver does not support io-uring).chopinstarts it again, up to three times, before the agent has started, and says so in its output. - The agent checks.
chopin service install, andchopin connect --install-servicebefore the machine is paired, start the agent once in a microVM of its image to send ACPinitialize, so a service is not installed, nor a pairing key spent, on an agent that can't start;--skip-checkleaves them out. The check that tells Chopin the agent's name when a connection opens runs the same way. connector.js, the downloaded script, runs agents in microVMs too, and carries the bridge its guests run, as the binary does.- What a microVM reads of yours is what it is shared: a Planner's checkout whole, and
the git directory a run clones from, its
configincluded. A token kept in a remote URL there, or a credential store file inside.git, is readable to the agent; keep credentials out of the repository's own files. - A
--sandbox-writefolder is written by agents as your user, setuid and setgid bits included, so don't name one other users of the machine can reach.
Chopin's GitHub App does, never your own login. Before each Planner command,
build or investigation starts, the connector asks Chopin for a token of the App
for that one repository. Chopin checks that the person it is for can push there:
whoever started the run, or you for a Planner on your machine. Commits are made
as the App's bot (<app>[bot]), and a build's pull request names and credits
the person who asked. A prototype's token only fetches its commit and is gone
before its agent starts. Setting the App up is in
Chopin's GitHub App identity.
| Variable | What it is |
|---|---|
GH_CONFIG_DIR |
A gh configuration of the launch's own, holding the current token. gh never reads yours. |
CHOPIN_GITHUB_TOKEN_FILE |
A file (mode 0600) holding the current token, renewed before it expires. |
CHOPIN_MCP_TOKEN_FILE |
A file holding a Chopin token for Chopin's own tools at /mcp. It is not a GitHub token. |
GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL and the committer's |
The App's bot. Your Git identity and signing settings are not used. |
CHOPIN_STARTER_LOGIN, CHOPIN_STARTER_NAME, CHOPIN_STARTER_EMAIL |
Who the work is for, for "Requested by" and a Co-authored-by trailer. |
Nothing a launch inherits reaches GitHub another way: GH_TOKEN,
GITHUB_TOKEN, other GH_* variables, GIT_ASKPASS, SSH_AUTH_SOCK,
GIT_SSH* and GIT_CONFIG_* are removed from its environment and from your
--env values, and Git never uses SSH (GIT_SSH_COMMAND=false).
When Chopin refuses a token, nothing starts. The connector says why, naming the
repository, and the run or Planner fails with that reason; see
Refusals. chopin status asks Chopin, without
a token being made, about each registered checkout's repository:
Checkouts: octo-org/score at /work/score; Chopin's GitHub App can't write to octo-org/score; it needs Contents and Pull requests write, which an admin of the repository must grant. This machine won't use its own GitHub login, so nothing runs there.
chopin status --json has the same as github: "ok", the refusal's code,
or "unknown" when Chopin couldn't be asked.
The connector's Git commands for a repository, and those of the Planner and
agent it starts, use the repository's https://github.com/ address and Chopin's
token, whatever your Git configuration says. A url.<base>.insteadOf or
pushInsteadOf rule that sends GitHub to SSH doesn't reach them, a checkout
whose origin is an SSH address is fetched and pushed over https, and your
credential helpers are not run. Nothing is written to your global configuration
or the checkout's own.
chopin updateThis installs the release your Chopin server asks for, verified like the
installer's download. A running service that uses this chopin restarts on
its own.
chopin unpairThis revokes the machine in Chopin and deletes its token. You can also open
Machines in Chopin's sidebar, which goes to /machines on your server, and
choose Disconnect machine… from the machine's … menu (on a phone, tap
the machine).
A running chopin connect then stops. The next chopin connect at a terminal
pairs again. To remove the service as well, run chopin service uninstall.
| Command | What it does |
|---|---|
chopin connect [--key <key>] --agent <id> |
Runs work from Chopin, in any repository you can push to, with a built-in agent. Pairs first if needed. |
chopin connect … -- <command> |
Runs any other ACP agent's command instead. |
chopin connect … --checkout <path> |
Uses your checkout for its repository's work instead of a clone. Repeat it for more; a bare path counts as one. |
chopin connect … --name <label> |
Names the machine in Chopin as it pairs. A machine paired already keeps its name; rename it on the Machines page. |
chopin connect … --install-service |
Connects once, then installs the service with what it ran. |
chopin connect … --keep-runs <n> |
Keeps the n most recently finished runs (default 15, 0 for all). |
chopin connect … --install <command> |
How to install an agent chopin has no recipe for in its microVMs' image. Repeat it. |
chopin connect … --planner-install <command> |
The same for the Planner command. |
chopin connect … --install-from <dir> |
A folder those commands read in the image's build, at /install-from, such as packages fetched with your sign-in. |
chopin connect … --sandbox-host <host> |
Lets agents reach one more host through the proxy. Repeat it. |
chopin connect … --sandbox-write <dir> |
Shares one more directory, writable, with every agent's microVM. Repeat it. |
chopin connect … --sandbox-hide <path> |
Hides one file or folder inside what agents are given. Repeat it. |
chopin pair [--label <name>] [--key <key>] |
Pairs this machine, or pairs it again. The label defaults to the hostname. |
chopin status [--json] |
Shows the server, pairing, the connector, the service and what it runs, the sandbox, your checkouts and clones, and the log. |
chopin service install [--allow-downgrade] [--skip-check] |
Copies what chopin connect last ran and runs it as a background service. |
chopin service status |
Prints running, stopped, restart-pending or not-installed. |
chopin service restart |
Restarts the service with the settings it has, for example after an update. |
chopin service uninstall |
Removes the service. The pairing, settings and past runs stay. |
chopin update [version] [--allow-downgrade] [--yes] |
Installs the release your server asks for, or the one you name. |
chopin unpair |
Revokes this machine in Chopin and deletes its token. |
Every command takes --base-dir <dir>, or CHOPIN_HOME, to keep its files
somewhere other than the default folder.
Start with chopin status and the log it names. For problems in the browser,
see
Trouble connecting.
Each message says what to run next. The first line of each:
| Message starts with | Do this |
|---|---|
curl or wget is required |
Install curl, for example sudo apt install curl, then run the command again. |
could not download |
Check your connection and any proxy (HTTPS_PROXY), then run the command again. |
… isn't writable by you |
Run sudo chown -R "$(id -un)" "$HOME/.local", then run the command again. |
… is not on your PATH |
Add the line the installer prints to your shell profile. The setup command runs chopin by its full path. |
This machine can't run Chopin's work |
Do what its Fix: line says, such as joining the kvm group, then run the command again. A Mac or an Arm machine can't be one of Chopin's machines; use a Linux or Windows x86_64 machine. |
chopin runs … in a microVM of its own |
Add --install '<the command that installs it>' (or --planner-install for a Planner command), then run the command again. |
… isn't inside a git checkout |
Give --checkout the folder of a clone from GitHub, or leave it out and chopin clones each repository as work needs it. |
… isn't a github.com repository |
Check git remote -v; Chopin connects clones of GitHub repositories. |
Can't reach Chopin at … |
Check CHOPIN_URL, your network and any proxy, then run the command again. |
Chopin refused the pairing key |
Generate a new script from Machines → Add machine → Cloud, then run it. |
… pairing key isn't allowed to use this Chopin |
Ask whoever runs Chopin to let your GitHub account or organization in, then generate a new script. |
You can't push to … on GitHub |
Chopin won't run that repository's work on this machine. Ask an owner for write access, or drop that --checkout. |
This machine has no checkout of … |
Your server gives machines no GitHub token to clone with. Run chopin connect --checkout <path> with a clone of that repository, then start the work again. |
… speaks connector protocol … |
Run the chopin update command the message names. |
… didn't answer ACP initialize |
The agent didn't start in its microVM. Check its --install commands, or what the message shows it printed, then run the command again. |
The microVM didn't start |
OpenVMM couldn't start the agent's microVM; the rest of the message is the end of OpenVMM's log. Fix what it names, such as /dev/kvm access or the Windows Hypervisor Platform, then start the work again. after 3 tries means the machine was too busy each time. |
… asks for permission in the terminal |
Run the command without --install-service and keep the terminal open. |
This machine is already paired with … |
To pair it for another account, run chopin unpair, then the command again. |
This machine is no longer paired with Chopin |
Run chopin pair, then connect again. |
The service has to keep running after you log out |
Have an administrator run sudo loginctl enable-linger "$(id -un)", then run the command again. |
"CHOPIN_URL is …, but chopin connect saved …" Install uses the server
chopin connect saved. Run chopin connect again with the server you want in
CHOPIN_URL, then chopin service install.
"Run chopin connect once first, then chopin service install." Run
chopin connect, wait for ✓ Connected., press Ctrl-C, then install again.
"This machine is not paired with …" The service can't pair. Run
chopin pair at a terminal, then the command the message names.
"This machine is no longer paired with Chopin." or "GitHub no longer
accepts this machine's authorization." Someone disconnected the machine, or
GitHub retired its authorization. Run chopin pair, then connect again.
"… didn't answer ACP initialize when started as the service would start
it." The agent didn't start in a microVM of its image. The message shows how it
ended and the first line it printed. Fix that, often its --install commands,
then install again. If the agent can't start without a terminal, pass
--skip-check.
"chopin can't reach your systemd user manager." Run the command in a login
session as the user who owns the service, not through su or sudo -u.
"… is already locked by a running connector" Another chopin connect, or
the service, is already connected with this base dir, and one connection serves
every repository. The second chopin connect stops before it builds or removes any
image. Stop the other one, or if chopin status shows nothing running, delete the
.lock file the message names.
For files, versions, the server rules, service internals, starting the Windows task at boot and status JSON, see the chopin CLI reference.