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 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:
pi install npm:@celestoai/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:
pip install celesto
celesto auth login
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
CELESTO_API_KEY="your-celesto-api-key"
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:
pi --celesto
The extension creates a Celesto computer, copies the project to /workspace, and routes Pi’s read, write, edit, and bash tools there.
Pi reports the computer name and shows /workspace as the active workspace.
4

Check the remote workspace

Run this inside Pi:
/celesto status
The result shows the computer name, status, cleanup behavior, and current synchronization revision.
5

Ask Pi to change the project

Give Pi a normal coding task. For example:
Add a health-check endpoint, run its tests, and explain the changes.
Pi reads files, edits code, and runs tests inside the Celesto computer. Press Esc to stop a long-running tool command.
6

Copy changes back locally

Run this inside Pi when you want the remote changes on your machine:
/celesto sync
Open your local editor or run git diff. The files changed by Pi now appear in your local project.

​
What runs locally and remotely

Your machineCelesto computer
Pi terminal interfaceProject copy in /workspace
Conversation and session historyread, write, edit, and bash operations
Model-provider credentialsShell commands and test processes
Celesto API key from your shell, .env, or CLI loginFiles created by Pi during the session
Pi treats /workspace on the Celesto computer as the active project while the session runs. Local files stay unchanged until synchronization.
The current extension uses compressed archives and base64 transfer. Treat your local Git repository as the durable copy: commit before long sessions, run /celesto sync regularly, and inspect git diff afterward.

​
Synchronize local and remote changes

The extension records a common revision after each successful synchronization. On the next /celesto sync, it compares both copies with that revision.
ChangeResult
Only the Celesto file changedPull the remote file to your local project
Only the local file changedPush the local file to /workspace
Both copies are identicalLeave the file unchanged
Both copies changed differentlyPreserve a conflict instead of overwriting either copy
One copy deleted an unchanged fileApply the deletion to the other copy
Conflicting remote files are saved under: 
.celesto-conflicts/<revision>/<path>.remote
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.
A failed or conflicted final synchronization keeps an extension-created computer. Reopen the Pi session and run /celesto sync to recover the work.

​
Reuse an existing Celesto computer

List your computers: 
celesto computer list
Start Pi with a computer name or ID from that list: 
pi --celesto --celesto-computer curie
A caller-selected computer is never deleted automatically. If it already contains files in /workspace, that remote workspace becomes the active copy. Run /celesto sync before editing locally.

​
Control computer cleanup

The extension normally synchronizes and deletes a computer it created when Pi exits. Keep that computer for another session by running: 
/celesto keep
Pi prints the exact celesto computer delete command you can use later. Computers selected with --celesto-computer are always caller-owned and are never deleted by the extension.

​
Files excluded from the cloud workspace

The extension reads .gitignore, then applies project-specific .celestoignore rules. It also excludes 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
fixtures/private/
*.large-test-data
A negated rule can explicitly include a path that another rule excluded:
.celestoignore
!fixtures/public-example.json

​
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 upload by default.
  • Celesto receives the project files that pass the exclusion rules.
  • Tool paths stay inside /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 the first session. Files intentionally included in the project can be copied to Celesto even when they contain sensitive application data.

​
Pi commands

CommandOutcome
/celesto statusShow the active computer, workspace, cleanup policy, and revision
/celesto syncReconcile the local project with /workspace
/celesto keepKeep an extension-created computer after Pi exits
!<command>Run a shell command in the Celesto computer
Update the installed package when a new version is available: 
pi update npm:@celestoai/pi

​
Troubleshoot setup

Install the Celesto CLI and sign in, then restart Pi:
pip install celesto
celesto auth login
pi --celesto
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 --version
pi install npm:@celestoai/pi
pi --help
Node.js must be version 22.19 or newer.
List existing computers and reuse one:
celesto computer list
pi --celesto --celesto-computer curie
Replace curie with a name from the list. Delete an unused computer when you no longer need it:
celesto computer delete --force curie
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.
The extension keeps the computer instead of deleting it. Reopen the same Pi session and run:
/celesto sync

​
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 July 10, 2026