Coming from Pi

Salambo builds on Pi's open-source engine and extension conventions, but owns its hosted runtime and supported API surface. Moving a project is not a promise that every Pi coding-agent feature or community package works hosted or in salambo dev. See credits.

Mapping

Import

Commit or back up first. The command moves files; it does not keep a copy of .pi/. From the project folder, logged in to your Salambo workspace:

salambo import

It moves the entries of .pi/ into .salambo/, rewrites imports of exactly @earendil-works/pi-coding-agent to @salambo-ai/agent in the extensions' source files, and writes salambo.yaml only if there is none. It does not rewrite package subpaths, dependency contents, or the project's package.json and lockfile: update your development dependencies yourself, then install @salambo-ai/agent and its typebox peer for your project's checks. It runs no package install and does not certify compatibility.

For local salambo dev, install @salambo-ai/agent as a dev dependency (npm install --save-dev @salambo-ai/agent): without it, salambo dev stops with Cannot find package '@salambo-ai/agent'. Hosted builds resolve the import themselves, so this concerns local runs only.

Refusals and how to fix them

Every refusal happens before anything moves, and names what to change. Fix it, then run salambo import again.

Links. The import doesn't move links. If .pi or salambo.yaml is a link, or .pi/ holds one outside a node_modules folder, it names every such link and stops:

salambo import doesn't move links, and these are links:
  .pi/prompts/current.md
Replace each link with what it points to, then run salambo import again. Or move the folder yourself (mv .pi .salambo), fix the links, and change the imports of @earendil-works/pi-coding-agent to @salambo-ai/agent.

This is deliberately broad: a link that would survive the move is refused too. Either way forward works: replace each link with what it points to and import again, or move the folder by hand, fix the links, and change the imports yourself.

Dependency links. Links inside node_modules folders in .pi/ belong to the package manager and don't block the import. One that points into .pi/ by an absolute path would break after the move, so it stops the import:

These dependency links point into .pi/ by an absolute path, which breaks when .pi/ moves:
  .pi/node_modules/tool
Delete .pi/node_modules (your package manager rebuilds it), run salambo import again, then reinstall in .salambo/.

A project that already uses only .salambo/, with its salambo.yaml and no remaining Pi imports, has nothing to import.

What the import doesn't check

• Links inside node_modules folders in .pi/ are listed, never followed, and only an absolute one into .pi/ is refused. A relative link in a node_modules folder that leaves .pi/ and comes back in by name (for example ../../.pi/data.txt) is not checked, and can break after the move. Package managers don't normally write such links, so it's most likely one you made by hand.
• Links outside .pi/, other than salambo.yaml, that point into it are not checked and can break: after the move, they point at a .pi/ path that no longer exists. Update them yourself.

When a node_modules folder moves, the import says:

Dependencies were moved; if they fail, reinstall them in .salambo/

If your dependencies fail after the import, reinstall them in .salambo/.

If the import stops part way, it says so: fix the cause it names, then run salambo import --yes to finish the move.

When it finishes, review the changes with git diff. Do not keep both folders: deploy refuses a project that has both .pi/ and .salambo/.

After the import, your own tsc or editor flags session_info_changed, ctx.ui.notify and ctx.ui.setStatus: they are not available on Salambo. Remove those calls. The deploy's build refuses session_info_changed, and any notify or setStatus call it can see, naming the file and line; a call it can't see fails the tool during a Turn, and the Turn still completes.

Before the first deploy

Create sandbox/workspace/ if it is absent, and keep a regular seed file such as sandbox/workspace/README.md in it; keep any existing seed files. A standalone Pi project may not have this directory, and the import does not create it. Deploy refuses a missing or excluded seed directory.

Configure the selected model's runtime credential with the deployment configuration guide; local credentials are not automatically hosted secrets. Then validate and deploy:

salambo doctor
salambo manifest --path . --json
salambo deploy

Community packages

The import keeps package declarations as written and reports calls that only work in a local Pi terminal; it does not convert every package into a supported hosted module. Hosted resource resolution accepts exact-version npm packages, public HTTPS git sources pinned to full 40-character commits, and repository-relative local directories. Selected resources must still pass the build and profile checks.

No blanket compatibility list is claimed. Native add-ons, CommonJS extension files, theme configuration and blocked install scripts are not a portable hosted extension surface. A package that imports a value @salambo-ai/agent does not export can fail the Salambo build. Check dependencies and peer requirements, not just a package's name.

Hosted versus local

Hosted custom providers, session-writing actions, provider hooks and compaction are not part of salambo dev. Locally, custom providers (including CLIProxyAPI), npm, git and local package resources, exec, provider, compaction and tree hooks, session-writing actions and other unlisted APIs are refused by name. Project-local supported tools and hooks work. Command, renderer and noninteractive UI calls are accepted without effect; they are not working UI features.

Local execution is not an OS sandbox. Read the exact warning and local lists, the hosted extension API, and Custom providers.

Models and wire compatibility

A built-in model removed from the catalogue can be refused before upload. Declared custom providers and agents with extensions follow the rules in Custom providers. azure-openai-responses maps silently to azure unless the agent declares its own provider with that name.

runtime in salambo.yaml is optional. salambo and the older pi spelling select the same runtime; prefer omitting the selector in new configuration. Hook names follow the current engine: register model_select and thinking_level_select rather than the older update names.