Run Pascal locally

The Pascal CLI creates a persistent local installation of the open-source editor, runs the editor and its MCP server in the background, and opens the editor in your browser. It does not create a JavaScript project or require a checkout of the Pascal repository. Your runtime and project data live outside the package-manager cache. The background process survives closing the terminal, while the runtime and projects also survive a reboot. Run editor again after a reboot to restart the process.

Requirements

Node.js 22.13 or newer
npm, which is included with standard Node.js installations and is used by pascal update
A browser if you want the CLI to open the editor automatically

The CLI supports macOS. Linux and Windows aren’t verified for the CLI yet. To run Pascal on a Linux server, use the Docker image instead.

Start the editor

Run the package directly:

npx @pascal-app/cli editor

After an interactive npx first run makes the editor healthy, Pascal installs that exact CLI version globally through npm. The shorter pascal command is then available immediately in the current terminal and future sessions. Pascal does not modify a shell profile or add an alias; npm places the executable in its configured global binary directory, which Node.js installations normally add to PATH. Non-interactive and --json runs do not install a global command. If npm cannot perform the global installation because of local permissions, the editor remains running and the CLI prints the equivalent npx commands plus the manual installation command. You can use an equivalent package runner to launch the CLI:

pnpm dlx @pascal-app/cli editor
bunx @pascal-app/cli editor

These forms still require npm to be available because the CLI’s update command uses npm to resolve another published release. Automatic installation of the shorter command currently applies to interactive npx first runs; use the global installation command below after pnpm dlx or bunx. On the first run, the CLI:

Prepares the local data directory, downloads the editor runtime for its version (pascal-web-runtime-<version>.tar.gz from the matching GitHub release), verifies it against the SHA-256 digest published inside the npm package, and installs it into ~/.pascal/runtime/<version>. Later runs reuse that installed copy.
Asks the operating system for an available loopback port.
Starts the editor and an authenticated MCP service as detached processes on separate operating-system-assigned loopback ports, then waits for both health checks.
Opens http://pascal.localhost:<port> in your browser and, for an interactive npx run, installs the same CLI version globally.
Prints the direct pascal status, pascal logs --follow, and pascal stop commands.

The reserved .localhost hostname resolves to the loopback service; it is not exposed to your network. The CLI shows each setup and startup stage in the terminal. It does not assume port 3000 or scan a fixed range, so it avoids competing with other development servers. A value passed with --port requests that specific port; when it is already occupied, Pascal reports the conflict and safely selects an available port instead. Running editor again reuses the healthy process instead of starting a second one; in that case --port does not move the existing process. Stop or restart the editor to select a new port. Use --no-open on a headless machine or when you do not want to launch a browser:

npx @pascal-app/cli editor --no-open

Use --foreground to keep the editor attached to the current terminal for debugging:

npx @pascal-app/cli editor --foreground --no-open

start and editor --no-open both download and install the runtime if needed and ensure it is running without opening a browser. start is the shorter lifecycle command for that operation. The npm package holds only the CLI and the MCP service, so the first start needs network access to GitHub. The download honours HTTPS_PROXY and NO_PROXY. On an offline machine, download the release archive elsewhere, copy it over, and pass it with --runtime; an archive is still checked against the published digest, so use the archive for the CLI version you run:

npx @pascal-app/cli editor --runtime ./pascal-web-runtime-1.0.6.tar.gz

--runtime also accepts an extracted runtime directory. pascal mcp connect never needs the web runtime. See The web editor runtime for the download URL and how verification works.

Install the command globally first

The interactive npx flow handles this automatically. You can instead install the shorter pascal command before starting the editor:

npm install --global @pascal-app/cli
pascal editor

Update the global command separately from the managed editor runtime:

npm install --global @pascal-app/cli@latest

Command reference

Every command, flag, JSON output, exit code and error code is in the Pascal CLI reference. The ones you’ll use most:

Command	What it does
`pascal editor`	Download and verify the runtime if needed, ensure it is running, and open it.
`pascal status`	Summarize editor and MCP health.
`pascal resume`	Open the most recently edited project.
`pascal logs --follow`	Follow the editor log.
`pascal stop`	Stop the managed editor and MCP processes.
`pascal doctor`	Check Node.js, storage, runtime, process health, and plugin state.

For a non-interactive installation where the global command is unavailable, prefix a command with your package runner—for example, npx @pascal-app/cli status. pascal agent claim and pascal agent status contact hosted Pascal. They read the agent key from PASCAL_API_KEY and do not store or print it. Claim requests a short-lived code; status verifies the key and reports its bounded claim state. Neither command uploads or links local projects. Direct integrations can call POST /api/auth/agent/claim/start and GET /api/auth/agent/status with the same Bearer key instead.

Update the editor

Install and activate the editor runtime that the latest published CLI package targets:

npx @pascal-app/cli update

Or select an exact published CLI package and the runtime it targets. Replace 1.0.0 with the version you need:

npx @pascal-app/cli update --version 1.0.0

An update installs the candidate under ~/.pascal/runtime, starts it through the normal health gate, and only leaves it active when that check passes. If activation fails, the CLI restores the previous runtime and restarts the previous editor when it was running. It does not replace ~/.pascal/data/pascal.db or update a globally installed pascal command.

Files and persistence

Path	Contents
`~/.pascal/runtime/<version>/`	Installed, versioned editor runtimes
`~/.pascal/data/pascal.db`	Local projects and scenes
`~/.pascal/logs/editor.log`	Detached editor output
`~/.pascal/run/editor.json`	Managed process identity, URL, and runtime version
`~/.pascal/run/mcp-token`	Private bearer token used only by the local MCP connector
`~/.pascal/run/current-runtime.json`	Active runtime pointer
`~/.pascal/plugins/`	Reserved storage for verified plugin artifacts
`~/.pascal/pascal.plugins.lock`	Managed plugin versions and integrity metadata

Runtime, data, logs, and process state have separate lifecycles. The CLI has no command that deletes project data. Runtime versions remain installed to make rollback possible, and pascal doctor warns after more than three versions accumulate. There is no automated prune command in the initial release. When disk space is constrained, stop Pascal and remove only version directories that are not named by current-runtime.json. Never remove the data directory when pruning runtimes. Before each detached start, an existing editor.log larger than 10 MiB rotates to editor.log.1. One previous log is retained. The paths above use Unix notation. On Windows, the same .pascal directory is under your user profile. Run npx @pascal-app/cli info --json to see the resolved paths on your machine.

Troubleshooting

Start with diagnostics, then inspect the process and log:

npx @pascal-app/cli doctor
npx @pascal-app/cli status
npx @pascal-app/cli logs --lines 200
npx @pascal-app/cli editor --foreground --no-open

Pascal selects an available port automatically. If you request a port with --port and another application owns it, the CLI reports the fallback port in the terminal.
If an interactive npx run cannot install the global command, it reports the npm failure without stopping the editor. Continue with npx @pascal-app/cli status or resolve your npm global-install permissions and run npm install --global @pascal-app/cli.
A reboot stops the editor process. Run npx @pascal-app/cli editor again; the initial CLI does not install a system startup service.
If the installed runtime for the current CLI version is incomplete or damaged, pascal editor downloads and verifies it again, then starts it. Project data remains separate under ~/.pascal/data.
If the runtime download fails, the error prints the archive URL and its SHA-256 digest. Fetch that archive on a connected machine and run pascal editor --runtime /path/to/pascal-web-runtime-<version>.tar.gz. An archive that doesn’t match the digest is refused.
The CLI refuses to stop a recorded PID unless its health endpoint returns the same Pascal instance identifier. This prevents a stale state file from stopping an unrelated process. If the recorded editor is alive but its health route is unavailable, inspect pascal status --json and use pascal stop --force; the CLI still verifies that the operating-system command points to the recorded runtime before signaling it.
The CLI binds only to loopback and does not expose an unauthenticated editor to your network. To serve Pascal to other devices or a public address, use the Docker image, which requires an admin password.

Self-host with Docker

To run Pascal on a server for yourself or a team, use the official container image, ghcr.io/pascalorg/pascal-editor. It holds the same editor runtime the CLI installs, is built for linux/amd64 and linux/arm64, and is tagged with the version of the @pascal-app packages; latest follows stable releases.

docker run -d -p 3000:3000 -v pascal-data:/data \
  -e PASCAL_ADMIN_PASSWORD=change-me \
  -e PASCAL_PUBLIC_URL=https://pascal.example.com \
  ghcr.io/pascalorg/pascal-editor:latest

Open your public URL and sign in with the admin password. Projects are stored in SQLite under /data, so keep the volume: without it, every project is lost when the container is recreated. To update, pull a newer tag and recreate the container with the same volume. The editor repository also has a docker-compose.yml that pulls the same image:

PASCAL_ADMIN_PASSWORD=change-me PASCAL_PUBLIC_URL=https://pascal.example.com docker compose up -d

Variable	What it does
`PASCAL_ADMIN_PASSWORD`	The one password that unlocks the instance. Required on any host that isn’t loopback.
`PASCAL_PUBLIC_URL`	The address people use to reach the editor. It’s read on each request, so one image serves any domain or port.
`PASCAL_SCENE_API_TOKEN`	Optional bearer token for agents and scripts calling `/api/scenes` and `/api/artifacts`.
`PASCAL_AUTH`	Set to `proxy` when a reverse proxy (basic auth, SSO) already authenticates every request; it replaces the password.
`PASCAL_DATA_DIR`	Where projects are stored. `/data` in the image.

How access works:

One workspace, one password. Every page and API sits behind /login. Everyone who signs in shares the same projects. Changing the password signs everyone out.
Closed by default. Reached from the network with no password set, the container serves only a setup page listing these variables. Reached at localhost, it’s open.
Agents use a token. Send PASCAL_SCENE_API_TOKEN as Authorization: Bearer …. The Connect an agent section of the settings page (/settings) shows the endpoint.
Health check. /api/health answers without signing in.

Nothing is public by default. In a project, click Share and turn on Public link. The project is then viewable read-only at /embed/<id> without the password, and the panel gives you an <iframe> snippet. Hide controls adds ?ui=0, which shows only the 3D view. Turning the link off makes the URL a 404 again.

Plugin development

The CLI currently manages the editor runtime; it does not install plugin code from a GitHub repository or npm. plugin add, plugin remove, plugin validate, and plugin pack are not available yet. The reserved plugin directory and lock file do not make the managed runtime extensible in this release. To develop a plugin today, follow Create a plugin, use the Nature plugin as the standalone example, and integrate the package through the reviewed discovery configuration in a host source checkout. The CLI-managed runtime cannot be modified to load that source package.

Connect a local AI agent

pascal editor starts MCP automatically. The MCP port remains dynamic to avoid collisions, while pascal mcp connect gives clients a stable stdio command that reads the private runtime state and connects to the current port. You do not copy the local token or manage another server.

# Configure Codex once
pascal mcp setup codex

Pascal agent skills 0.1.7 already supplies the same local connector to Claude Code. If that plugin is installed, do not also run pascal mcp setup claude. Remove a previous user-scoped manual entry before reloading or restarting Claude Code:

claude mcp remove --scope user pascal

Use /mcp to remove or disable any project- or local-scoped duplicate so only plugin:pascal-agent-skills:pascal remains active. If you use Claude Code without the plugin, pascal mcp setup claude remains the manual setup path. For Cursor, Claude Desktop, and other mcp.json clients:

{
  "mcpServers": {
    "pascal": {
      "command": "pascal",
      "args": ["mcp", "connect"]
    }
  }
}

The connector starts Pascal automatically if it is stopped. Ask the agent to read pascal://agent-guide, call list_scenes, then load_scene before editing an existing project. MCP saves use the same ~/.pascal/data/pascal.db database and appear in the browser through the local scene event stream. setup requires the stable pascal command and refuses to overwrite an existing Pascal MCP entry. Run pascal mcp config to print the generic JSON or configure a different client manually. To edit projects in your hosted Pascal account instead, use the authenticated hosted setup in Connect an AI agent. Claude plugin users must disable the plugin-provided local server in /mcp before adding the hosted connection.

Integrate

Extend Pascal

Requirements

Start the editor

Install the command globally first

Command reference

Update the editor

Files and persistence

Troubleshooting

Self-host with Docker

Plugin development

Connect a local AI agent

​Requirements

​Start the editor

​Install the command globally first

​Command reference

​Update the editor

​Files and persistence

​Troubleshooting

​Self-host with Docker

​Share a project publicly

​Plugin development

​Connect a local AI agent

Requirements

Start the editor

Install the command globally first

Command reference

Update the editor

Files and persistence

Troubleshooting

Self-host with Docker

Share a project publicly

Plugin development

Connect a local AI agent