> ## Documentation Index
> Fetch the complete documentation index at: https://docs.celesto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Pi coding agent in the cloud

> Run Pi coding agent remotely on a Celesto cloud computer, keep model credentials local, push and sync project files explicitly, and troubleshoot common setup issues.

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.

<CardGroup cols={2}>
  <Card title="Start on Celesto Free" icon="cloud" href="https://celesto.ai/pi-coding-agent">
    Create an account without a credit card and run Pi tools on an included cloud computer.
  </Card>

  <Card title="Open the Pi package" icon="box" href="https://pi.dev/packages/@celestoai/pi">
    Review the package details and install `@celestoai/pi` from the official Pi package catalog.
  </Card>
</CardGroup>

## Before you start

You need:

* Node.js 22.19 or newer.
* [Pi](https://github.com/earendil-works/pi) installed and configured with a model provider.
* A Celesto account and API key. Create the key at [celesto.ai](https://celesto.ai) under **Settings > Security**.
* A local project directory you want Pi to edit.

<Note>
  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](/smolvm/features/coding-agents).
</Note>

## Run Pi remotely

<Steps>
  <Step title="Install the Celesto extension">
    Install the package once through Pi:

    ```bash theme={null}
    pi install npm:@celestoai/pi
    ```

    <Check>
      Run `pi --help` and confirm that `--celesto` appears under extension flags.
    </Check>
  </Step>

  <Step title="Sign in to Celesto">
    Install the Celesto CLI and save your API key locally:

    ```bash theme={null}
    pip install celesto
    celesto auth login
    ```

    <Check>
      Run `celesto auth status` and confirm that an API key is saved.
    </Check>

    You can instead export the key or add it to the project's local `.env` file:

    ```bash .env theme={null}
    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`.
  </Step>

  <Step title="Start Pi from your project">
    Change to the project directory, then run:

    ```bash theme={null}
    pi --celesto
    ```

    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.

    <Check>
      Pi reports the computer name and shows `$HOME/workspace` as the active workspace.
    </Check>
  </Step>

  <Step title="Push your project to the computer">
    Copy the current local project to the remote workspace:

    ```text theme={null}
    /celesto push
    ```

    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.

    <Check>
      Pi reports how many files were copied and warns you about any skipped oversized or unsafe files.
    </Check>

    Push refuses to copy your filesystem root or your home directory. Start Pi from an actual project folder.
  </Step>

  <Step title="Check the remote workspace">
    Run this inside Pi:

    ```text theme={null}
    /celesto status
    ```

    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.
  </Step>

  <Step title="Ask Pi to change the project">
    Give Pi a normal coding task. For example:

    ```text theme={null}
    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.
  </Step>

  <Step title="Sync changes back locally">
    Run this inside Pi when you want the remote changes on your machine:

    ```text theme={null}
    /celesto sync
    ```

    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.

    <Check>
      Open your local editor or run `git diff`. The files changed by Pi now appear in your local project.
    </Check>
  </Step>
</Steps>

## What runs locally and remotely

| Your machine                                          | Celesto computer                                               |
| ----------------------------------------------------- | -------------------------------------------------------------- |
| Pi terminal interface                                 | `$HOME/workspace` (starts empty, populated by `/celesto push`) |
| Conversation and session history                      | `read`, `write`, `edit`, and `bash` operations                 |
| Model-provider credentials                            | Shell commands and test processes                              |
| Celesto API key from your shell, `.env`, or CLI login | Files created by Pi during the session                         |
| Local project files until you run `/celesto push`     | Files copied by `/celesto push` and `/celesto sync`            |

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`.

<Warning>
  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.
</Warning>

## 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.

| Change                             | Result                                                 |
| ---------------------------------- | ------------------------------------------------------ |
| Only the Celesto file changed      | Pull the remote file to your local project             |
| Only the local file changed        | Push the local file to `$HOME/workspace`               |
| Both copies are identical          | Leave the file unchanged                               |
| Both copies changed differently    | Preserve a conflict instead of overwriting either copy |
| One copy deleted an unchanged file | Apply the deletion to the other copy                   |

Conflicting remote files are saved under:

```text theme={null}
.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.

<Info>
  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.
</Info>

## Reuse an existing Celesto computer

List your computers:

```bash theme={null}
celesto computer list
```

Start Pi with a computer name or ID from that list:

```bash theme={null}
pi --celesto --celesto-computer curie
```

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:

```text theme={null}
/celesto keep
```

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`:

```gitignore .celestoignore theme={null}
fixtures/private/
*.large-test-data
```

A negated rule can explicitly include a path that another rule excluded:

```gitignore .celestoignore theme={null}
!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 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

| Command           | Outcome                                                                                   |
| ----------------- | ----------------------------------------------------------------------------------------- |
| `/celesto status` | Show the active computer, workspace, cleanup policy, and revision                         |
| `/celesto push`   | Copy the current local project to the empty remote workspace and record a shared revision |
| `/celesto sync`   | Reconcile the local project with `$HOME/workspace` after a push                           |
| `/celesto keep`   | Keep 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:

```bash theme={null}
pi update npm:@celestoai/pi
```

## Troubleshoot setup

<AccordionGroup>
  <Accordion title="No Celesto credentials were found">
    Install the Celesto CLI and sign in, then restart Pi:

    ```bash theme={null}
    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.
  </Accordion>

  <Accordion title="Pi does not recognize --celesto">
    Confirm Node.js and Pi meet the requirements, then reinstall the extension:

    ```bash theme={null}
    node --version
    pi install npm:@celestoai/pi
    pi --help
    ```

    Node.js must be version 22.19 or newer.
  </Accordion>

  <Accordion title="The free plan has no available computer slot">
    List existing computers and reuse one:

    ```bash theme={null}
    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:

    ```bash theme={null}
    celesto computer delete --force curie
    ```
  </Accordion>

  <Accordion title="Push refuses to copy the current directory">
    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.
  </Accordion>

  <Accordion title="Sync reports no shared revision">
    `/celesto sync` requires an initial push. Run:

    ```text theme={null}
    /celesto push
    ```

    After the push succeeds, `/celesto status` shows a revision ID and sync works normally.
  </Accordion>

  <Accordion title="Synchronization reports conflicts">
    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.
  </Accordion>

  <Accordion title="A command keeps running">
    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.
  </Accordion>

  <Accordion title="Another workspace transfer is already running">
    Only one `/celesto push` or `/celesto sync` runs at a time. Wait for the current transfer to finish, then rerun the command.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Manage Celesto computers" icon="server" href="/cloud/computers">
    Learn about templates, resources, ports, command execution, and lifecycle controls.
  </Card>

  <Card title="Authenticate the SDK" icon="key" href="/cloud/authentication">
    Learn where to create API keys and how the CLI stores credentials.
  </Card>

  <Card title="Compare plans" icon="credit-card" href="https://celesto.ai/pricing">
    Review free-plan limits and paid capacity for longer or parallel sessions.
  </Card>

  <Card title="View the extension source" icon="github" href="https://github.com/CelestoAI/sdk/tree/main/pi">
    Review the implementation, tests, and package README.
  </Card>
</CardGroup>