Skip to main content
Run Pi’s coding tools on a Celesto cloud computer while the Pi interface stays on your machine. Your project runs in an isolated workspace, and you choose when to copy files to the remote workspace and when to bring changes back locally. A Celesto computer is a remote Linux computer created for your work. Model credentials are the API keys or login details Pi uses to access your chosen AI model. The Celesto extension keeps those credentials, your conversation history, and the Pi terminal interface on your machine.

Start on Celesto Free

Create an account without a credit card and run Pi tools on an included cloud computer.

Open the Pi package

Review the package details and install @celestoai/pi from the official Pi package catalog.

​
Before you start

You need:
  • Node.js 22.19 or newer.
  • Pi installed and configured with a model provider.
  • A Celesto account and API key. Create the key at celesto.ai under Settings > Security.
  • A local project directory you want Pi to edit.
This guide keeps Pi local and sends its coding tools to Celesto. If you want to run the entire Pi process inside a local SmolVM instead, see Coding agents in SmolVM.

​
Run Pi remotely

1

Install the Celesto extension

Install the package once through Pi:
Run pi --help and confirm that --celesto appears under extension flags.
2

Sign in to Celesto

Install the Celesto CLI and save your API key locally:
Run celesto auth status and confirm that an API key is saved.
You can instead export the key or add it to the project’s local .env file:
.env
Add .env to .gitignore. The bundled Celesto TypeScript SDK checks the shell environment first, then .env, then credentials saved by celesto auth login.
3

Start Pi from your project

Change to the project directory, then run:
The extension creates a Celesto computer with an empty $HOME/workspace and routes Pi’s read, write, edit, and bash tools there. Nothing is copied from your machine yet.
Pi reports the computer name and shows $HOME/workspace as the active workspace.
4

Push your project to the computer

Copy the current local project to the remote workspace:
This replaces the contents of $HOME/workspace with the files in your local project. Run it once at the start of a session, before asking Pi to read or edit code.
Pi reports how many files were copied and warns you about any skipped oversized or unsafe files.
Push refuses to copy your filesystem root or your home directory. Start Pi from an actual project folder.
5

Check the remote workspace

Run this inside Pi:
The result shows the computer name, status, cleanup behavior, and current synchronization revision. After a successful push, the revision changes from not synchronized to an ID.
6

Ask Pi to change the project

Give Pi a normal coding task. For example:
Pi reads files, edits code, and runs tests inside the Celesto computer. Press Esc to stop a long-running tool command.
7

Sync changes back locally

Run this inside Pi when you want the remote changes on your machine:
Sync reconciles both copies against the last shared revision. It requires a prior /celesto push (or an already-shared revision) — without one, it reports that the workspace has no shared revision.
Open your local editor or run git diff. The files changed by Pi now appear in your local project.

​
What runs locally and remotely

The remote workspace is empty when Pi starts. Files only exist there after you run /celesto push. From that point on, $HOME/workspace is the active copy that Pi’s tools operate on, and your local project stays unchanged until you run /celesto sync.
The current extension uses compressed archives and base64 transfer, and it never copies files automatically — not on connect and not on exit. Treat your local Git repository as the durable copy: commit before long sessions, run /celesto sync before ending a session, and inspect git diff afterward.

​
Explicit push and sync lifecycle

A typical session moves files in a fixed order:
  1. Push once. /celesto push copies the local project into the empty remote workspace and records a shared revision. It refuses to run if a shared revision already exists — use /celesto sync from that point onward.
  2. Work remotely. Pi’s tools read, write, edit, and run shell commands inside $HOME/workspace. Your local files are not touched.
  3. Sync when you want the changes locally. /celesto sync compares both copies with the shared revision and moves changed files in the direction they changed.
Only one workspace transfer runs at a time. If a push or sync is already in progress, a second attempt reports that another Celesto workspace transfer is running.

​
Synchronize local and remote changes

The extension records a shared revision after each successful push or sync. On the next /celesto sync, it compares both copies with that revision. Conflicting remote files are saved under:
If the remote copy was deleted, the extension writes a .remote-deleted marker. Resolve the local file, remove the conflict copy when you no longer need it, then run /celesto sync again.
Sync is the only way to bring remote changes back to your machine. Pi never syncs automatically when it exits, so make sure to run /celesto sync before ending a session you care about.

​
Reuse an existing Celesto computer

List your computers:
Start Pi with a computer name or ID from that list:
A caller-selected computer is never deleted automatically. Any files already in $HOME/workspace remain untouched until you explicitly run /celesto push or /celesto sync. A non-empty legacy /workspace is moved to $HOME/workspace automatically when the home workspace is empty. If the remote workspace already contains a project from a previous session, run /celesto sync to reconcile it with your local copy. If the remote workspace is empty (or you want to replace it with the current local project), run /celesto push.

​
Control computer cleanup

When Pi exits, an extension-created computer is deleted without any automatic sync. Any changes you have not copied back with /celesto sync are lost. Keep the computer for another session by running:
Pi prints the exact celesto computer delete command you can use later. Keeping the computer preserves the remote workspace, but you are still responsible for retaining a local copy of anything you want to keep — run /celesto sync before exiting. Computers selected with --celesto-computer are always caller-owned and are never deleted by the extension.

​
Files excluded from explicit transfers

/celesto push and /celesto sync read .gitignore and then apply project-specific .celestoignore overrides. They also exclude common secrets and large generated directories by default, including:
  • .env files and common credential files.
  • Pi, cloud-provider, SSH, and package-manager credentials.
  • node_modules, build output, coverage output, and .next.
  • Symbolic links.
  • Individual files larger than 25 MB.
  • .celesto-conflicts and the synchronization metadata file.
The .git directory remains available so Pi can inspect branches, status, and diffs. Add extra exclusions to .celestoignore:
.celestoignore
A negated rule can explicitly include a path that another rule excluded:
.celestoignore

​
Security boundary

The extension is designed so the model connection stays local:
  • Pi calls your model provider from your machine.
  • Model credentials are not forwarded as shell environment variables.
  • The Celesto API key stays in the local Pi process and is not forwarded to the remote computer.
  • Local .env files remain excluded from workspace transfers by default.
  • Celesto only receives files you push or sync that pass the exclusion rules.
  • Tool paths stay inside $HOME/workspace.
  • Shell commands can use the rest of the isolated Celesto computer.
  • Remote command output streams back to the local Pi interface.
Review .gitignore and .celestoignore before your first push. Files intentionally included in the project can be copied to Celesto even when they contain sensitive application data.

​
Pi commands

Update the installed package when a new version is available:

​
Troubleshoot setup

Install the Celesto CLI and sign in, then restart Pi:
Alternatively, export CELESTO_API_KEY in the same shell or add it to the project’s local .env file.
Confirm Node.js and Pi meet the requirements, then reinstall the extension:
Node.js must be version 22.19 or newer.
List existing computers and reuse one:
Replace curie with a name from the list. Delete an unused computer when you no longer need it:
The extension refuses to push from your filesystem root or home directory to avoid uploading unrelated files. Exit Pi, change into an actual project directory, restart with pi --celesto, and run /celesto push again.
/celesto sync requires an initial push. Run:
After the push succeeds, /celesto status shows a revision ID and sync works normally.
Open .celesto-conflicts/<revision>/ in your local project. Compare each .remote file with the local path, keep the intended content, and run /celesto sync again.
Press Esc in Pi. The extension cancels the output stream and terminates the remote process group. Run /celesto status to confirm the computer remains connected.
Only one /celesto push or /celesto sync runs at a time. Wait for the current transfer to finish, then rerun the command.

​
Next steps

Manage Celesto computers

Learn about templates, resources, ports, command execution, and lifecycle controls.

Authenticate the SDK

Learn where to create API keys and how the CLI stores credentials.

Compare plans

Review free-plan limits and paid capacity for longer or parallel sessions.

View the extension source

Review the implementation, tests, and package README.
Last modified on August 14, 2026